NotePom

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

Annotations already provide the safety profile: readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the precondition that the invitation must be 'exact' and 'pending', but does not describe side effects, failure modes, or consequences of acceptance beyond what annotations convey.

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

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

A single, front-loaded sentence with no filler. Every word adds meaning, and the most important qualifiers ('exact', 'pending', 'addressed to this account') are included early. It is appropriately concise for the action described.

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 required idempotencyKey parameter is completely unexplained and the workflow for obtaining an invitationId is not referenced (e.g., via list_collaboration_invitations), the description is not fully complete. The presence of an output schema helps, but the missing parameter semantics leave a significant gap for an agent.

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 some context for invitationId by referring to an 'invitation', but it entirely omits the idempotencyKey parameter, its purpose, and how to construct it. The schema only gives format constraints, which is insufficient for an agent to correctly supply both required parameters.

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

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

The description clearly states a specific action ('Accept') on a specific resource ('exact pending collaboration invitation addressed to this account'). It distinguishes itself from related siblings like list_collaboration_invitations, invite_collaborator, and revoke_collaboration_invitation by focusing on the acceptance operation.

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 usage when an exact pending invitation exists for this account, but it does not explicitly state when to use this tool versus alternatives, nor does it reference sibling tools like list_collaboration_invitations for finding the invitation ID. There is no exclusion or alternative guidance.

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

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

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?

Annotations already mark the operation destructive and non-idempotent; the description adds meaningful context by enumerating exactly what will be destroyed, stating permanence, and calling it terminal. This goes well beyond the booleans and contains 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?

A single dense sentence that front-loads the action and scope before the safety gate. Every clause earns its place; there is no filler or redundant restatement of the title.

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

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

For a destructive, irreversible account deletion, the description supplies a solid human-approval gate, the exact scope of destruction, and terminality. However, it never explains how the required idempotencyKey should be generated or used, leaving one meaningful gap for a non-idempotent destructive 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?

Schema coverage is only 50%: the confirmation parameter is fully described by its const and schema description, but idempotencyKey has no description and the tool description does not explain it either. The phrase 'exact confirmation value' only restates what the schema already says, so the description fails to compensate for the undocumented 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 names a specific verb ('Permanently delete') and a clearly bounded resource: only the currently authenticated agent account plus all associated data (workspace, uploads, public pages, history, collaborations, credentials). It also distinguishes itself from the many content-deletion siblings by emphasizing the account-wide, account-owner scope.

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

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

It explicitly gates invocation: call only after a human operator explicitly requests deletion and provides the exact confirmation value. The phrase 'terminal operation' warns against casual or repeated use, giving an agent a clear behavioral precondition.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: 'persistent workspace memory', 'current autonomous-agent signup mode', and 'safe bootstrap sequence' explain what the agent will discover and receive. This is useful and consistent 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 tightly worded sentence with an upfront imperative. Every clause adds distinct information: sequencing, purpose, memory nature, signup-mode inspection, and bootstrap output. There is no filler or redundancy.

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

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

For a no-parameter capability-discovery tool with an output schema present and safety annotations covering side effects, the description is complete. It tells the agent when to call it, what to expect conceptually, and what it will receive. Nothing critical is missing.

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

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

The tool has zero parameters and the input schema is empty, so parameter semantics are trivial. The description correctly does not attempt to explain nonexistent parameters, and the baseline of 4 applies.

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

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

The description opens with a clear directive ('Call this first') and states specific capabilities: discovering NotePom as persistent workspace memory, inspecting the autonomous-agent signup mode, and receiving a safe bootstrap sequence. This distinguishes it from the sibling tools, which are all individual operations rather than a capability-discovery bootstrap tool.

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

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

The description explicitly says to call this tool first, establishing clear sequencing and bootstrap context. It does not explicitly name alternatives or exclusion conditions, but given this is the discovery/initialization tool among many operational siblings, the usage context is clear enough.

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

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

Annotations already declare 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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the description doesn't need to restate those. It adds meaningful behavioral context: email invitations can be created before the recipient has an account, and the recipient must explicitly accept after signing in. This goes beyond the schema and annotations, though it doesn't detail side effects like whether an existing collaborator is replaced or whether the invitation expires.

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

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

Three sentences, each carrying distinct information: the core action, the workspace-sharing special case, and the email-invitation behavior. No filler or repetition of schema fields. The most important scoping information is front-loaded.

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

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

The tool has an output schema, so return values don't need explanation. The description covers the main behavioral nuances (email pre-account invitations, explicit acceptance, whole-workspace sharing). It could be more complete by noting what happens on duplicate invitations or whether the idempotencyKey prevents duplicates, but for an invitation tool with annotations and an output schema, this is largely sufficient.

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 33%, so the description must compensate. It does clarify the key parameter semantics: identity can be a username or email, entityType folder with rootFolderId enables whole-workspace sharing, and email invitations can target pre-account users. However, it doesn't explain workspaceId, idempotencyKey, or language beyond what the schema already says, so it doesn't fully cover the gap.

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 ('Invite') and resource ('collaborator by NotePom username or email'), and distinguishes the tool from siblings like revoke_collaboration_invitation and accept_collaboration_invitation. It also clarifies the two entity types and the special case of sharing the entire workspace as a Drive, which makes the tool's purpose unmistakable.

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 explicitly tells when to use this tool (invite by username or email) and gives a concrete alternative path for sharing the whole workspace (entityType folder with rootFolderId from list_workspace). It also explains the email-invitation flow for recipients without an account, which is essential usage context not inferable from the schema.

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?

Annotations already indicate this is a non-readonly, non-idempotent, open-world operation. The description adds meaningful behavioral detail: it stores a returned one-time key in the host secret store and reconnects with it as a Bearer credential. 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?

Two sentences, front-loaded with the trigger condition, then the action and follow-up steps. No wasted words; every phrase adds necessary operational context.

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 high-level process is described well, but with 4 parameters and 0% schema description coverage, the description leaves out essential meaning for the input fields. The presence of an output schema reduces some burden, but not enough to make this definition complete for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not mention any of the four parameters: identifier, password, email, language. The agent gets no help understanding required vs optional fields or their 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?

The description states a clear action: 'create a distinct NotePom agent account' when persistent memory is requested and no credentials exist. It also explains the credential lifecycle, which distinguishes this from sibling tools like verify_agent_account and delete_own_agent_account.

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 a concrete trigger condition: 'When persistent memory is requested and no credentials exist.' It does not explicitly name alternatives or say when not to use the tool, but the conditional context makes the usage scope clear.

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

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

Annotations already declare 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 annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds that the operation is scoped to an exact invitation from the authenticated workspace, but it doesn't elaborate on consequences, reversibility, or idempotency behavior beyond what annotations already signal. 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, front-loaded sentence with no filler. Every word contributes: the verb, the exactness requirement, and the workspace scope. It is appropriately sized for a narrow two-parameter tool.

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

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

With an output schema present and annotations covering destructiveness and idempotency, the description is mostly sufficient for a simple operation. However, the unexplained idempotencyKey is a real gap: an agent may know the tool is destructive but not know how to supply a valid idempotency key. The description also leaves the distinction from revoke_collaborator implicit.

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 explain the parameters. The phrase 'exact invitation' loosely suggests invitationId, but idempotencyKey's purpose and generation are completely unexplained. The description does not compensate for the missing schema descriptions.

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 and object: 'Revoke an exact invitation issued from the authenticated workspace.' It clearly distinguishes this from sibling tools like revoke_collaborator by targeting an invitation rather than an active 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 clear usage context: this applies only to a specific, exact invitation and only to invitations issued from the authenticated workspace. It does not explicitly mention alternatives or when not to use it, but the scope is clear and excludes looking up or accepting 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 and idempotentHint=true, so the description does not need to restate them. It adds useful scope ('one exact grant owned by the authenticated workspace'), but it does not discuss consequences such as irreversibility or effects on the collaborator's access beyond revocation.

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, placing the verb and core resource first. Every phrase ('one exact', 'owned by the authenticated workspace') 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 tool is simple, has annotations covering destructive and idempotent behavior, and has an output schema, so the description can stay short. However, it leaves an agent without an explicit differentiator from revoke_collaboration_invitation and does not clarify the semantics of idempotencyKey, making it only minimally 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 must compensate, but it only hints at grantId via 'one exact collaboration grant' and says nothing about idempotencyKey, its format, or its role. The schema's field names and types are the only real semantic source, which is insufficient.

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') and resource ('collaboration grant') and adds the scope 'owned by the authenticated workspace.' This clearly distinguishes the action from related sibling tools such as 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?

It implies the tool is for an existing, exact collaboration grant rather than a pending invitation, but it never explicitly states when to prefer this tool over revoke_collaboration_invitation or other alternatives. The context is present only by inference from the wording.

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?

The description discloses that the tool replaces the body, is idempotent, and supports an optional expected revision, which adds behavioral context beyond the raw annotations. However, it does not explain what happens on a revision mismatch, whether the note must already exist, or the consequences of replacing the body. The idempotency hint is already in annotations, so the description adds only moderate value here.

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

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

The description is a single sentence with no filler, and the core action plus key properties are front-loaded. The phrase 'from Markdown' is slightly awkward and 'exact' is ambiguous, which prevents a perfect score, but it remains 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?

Given five parameters, zero schema description coverage, and no usage guidance, the description is not complete enough for correct invocation. It fails to clarify idempotency semantics, expectedRevision mismatch behavior, whether the note must exist, or when to prefer this over sibling tools. The output schema may cover return values, but substantial invocation context is still 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%, and the description only partially compensates. It mentions Markdown and expected revision but does not explain the roles of workspaceId, noteId, or idempotencyKey, nor how expectedRevision behaves when omitted or mismatched. The parameter names are somewhat self-explanatory, but the description does not carry the load needed for such low schema 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 the specific verb 'Replace' and names the resource 'the shared body of an exact collaboration note,' which clearly identifies the operation. It adds detail beyond the title by mentioning idempotency and expected revision, though it does not explicitly differentiate this tool from sibling update tools like upsert_note 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?

The description provides no guidance on when to use this tool versus alternatives such as upsert_note or update_public_page. It does not state prerequisites, exclusions, or conditions, so the agent must infer usage from the tool name and resource type.

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?

Annotations already declare idempotent=true, destructive=false, and readOnly=false, so the safety profile is covered; the description adds non-obvious behavior such as the upload_file dependency, media rejecting bytes/URLs/base64, and the folderId-omitted default to workspace root. It still omits update-conflict semantics for expectedUpdatedAt and whether contentMode replace discards existing content.

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?

Five sentences, front-loaded with the core verb and resource, then progressively narrower guidance about content fields, media prerequisites and folder placement. Dense but each sentence carries distinct operational information; a couple could be tightened.

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 so return values need not be described, and annotations cover the safety profile. For a 10-parameter mutation tool with 20% schema coverage, the description leaves too many parameters (idempotencyKey, expectedUpdatedAt, contentMode, noteId) unexplained for an agent to call it confidently.

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% across 10 parameters, so the description must carry weight, and it does explain markdown, pretextBlocks, media/fileId and folderId. However it is silent on title, noteId, idempotencyKey, expectedUpdatedAt, parentNoteId and, most importantly, contentMode's replace/append/prepend effect on an upsert.

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 opening sentence names a specific verb pair (create or update) and resource (a real Pretext note), which is enough for an agent to distinguish it from read-side siblings like get_note. It does not explicitly contrast itself with update_collaboration_note or explain the create-vs-update trigger (noteId presence), so it falls short of a 5.

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

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

The description gives concrete routing guidance: markdown for simple content, pretextBlocks for colors/typography/links/animations, and a hard prerequisite to call upload_file before populating media. It stops short of stating when NOT to use this tool or how it relates to the collaboration-note siblings.

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.