docuwriter

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

Annotations only declare the safety profile (readOnly false, openWorld true, destructive false); the description adds genuinely new behavior — that it is state-changing, that it runs 'after authorization', and that targeting a public Space makes the content publicly accessible. That public-exposure warning is exactly the kind of consequence an agent needs. No idempotency or duplicate-handling detail, so not a 5.

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

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

Three short clauses ordered as trigger, behavior/consequence, then parameters — well front-loaded with no filler. Slightly dense in the first clause, but nothing wasted.

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 4-param create operation with full schema coverage and safety annotations, the description covers purpose, side effects and required inputs adequately. With no output schema present, it could say what is returned (e.g. the new Space item ID), which is the only real gap.

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

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

Schema coverage is 100% and each parameter already carries its own description (including 'Call list-spaces first' / 'Call list-generations first'), so the schema does the heavy lifting. The description only restates which params are required and optional, adding no format or constraint detail beyond the schema — baseline 3.

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 ('add/save/publish') and resource ('existing generated output/result') into a documentation Space. The word 'existing' cleanly separates it from generate-and-add-documentation and generate-*-and-add siblings, which produce content rather than filing an already-produced generation.

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 opening clause gives an explicit trigger ('when the user wants to save, publish, or add an existing generated output'), which is clear usage context. It stops short of naming an alternative or a when-not condition, so it falls just below 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 mark destructiveHint=true and readOnlyHint=false, and the description goes further by specifying exactly what changes: it writes suggested content to the target document and marks the suggestion applied. It also flags that authorization is involved, adding useful operational context beyond the annotation booleans.

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

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

Three short sentences, with the usage trigger front-loaded, followed by the effect and the prerequisite. Every sentence contributes necessary information; there is no filler or redundant restatement of the tool name.

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

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

For a simple single-parameter mutation tool with destructive annotations already in place, the description covers the action, the state change, the authorization requirement, and the source of the required ID. It does not explicitly mention alternatives for rejecting or bulk-applying suggestions, but that is a minor gap given the sibling list and the clear scope.

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

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

Schema coverage is 100% and the parameter description already defines suggestion_id as the numeric ID of the RepositoryDocSuggestion. The description adds extra value by telling the agent the ID must come from list-space-suggestions, which is not present in the schema.

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

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

The description names a specific verb ('apply or accept'), a specific resource ('one pending Autopilot/repository-sync documentation suggestion'), and the concrete effect (writes content to the target Space document and marks it applied). This clearly distinguishes it from sibling tools like discard-space-suggestion, snooze-space-suggestion, and bulk-manage-space-suggestions.

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 opens with 'Use this when the user wants to apply or accept...' and instructs that suggestion_id must come from list-space-suggestions. It does not explicitly enumerate when to prefer bulk-manage-space-suggestions or discard-space-suggestion, but the single-suggestion scope is clear enough for an agent to route correctly.

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?

Describes the state-changing nature, notes authorization requirement, and clarifies that it does not delete the generation. The annotation destructiveHint: false aligns with the description, so no contradiction exists.

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

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

The description is succinct, with only two sentences that convey all essential information without redundancy. It is well-structured 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?

The tool is simple with a single parameter, and the description covers the action, effect, prerequisites, and non-destructive nature. No additional context is needed 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?

The schema already provides the parameter description, but the tool description adds 'from list-generations,' which gives valuable context on how to obtain the generation_id. This minor addition justifies a slight bonus.

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

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

The description clearly states the action (archive, hide, or remove) on a specific resource (generation) and its effect (removing from active list without deletion). It distinguishes from destructive actions by explicitly noting 'without deleting it'.

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

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

Provides an explicit trigger condition ('when the user wants to archive, hide, or remove an existing generation from the active generation list') and clarifies non-destructive intent. Also mentions the prerequisite of calling list-generations, which serves as 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?

The description explicitly flags the action as destructive and state-changing, detailing what happens: bulk apply updates multiple Space documents, and bulk discard removes suggestions after authorization. This goes beyond the annotations by explaining specific effects.

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

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

The description is concise, with the main purpose front-loaded in the first sentence. It packs essential information (destructive nature, prerequisites) into a short, well-structured text 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?

Given the tool's destructive nature and lack of output schema, the description provides enough context about its operation and requirements. It does not mention result reporting or atomicity, but this is not essential for basic usage.

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?

Both parameters are clearly described: 'ids' as numeric suggestion IDs, and 'action' as the operation to perform (apply or discard). The descriptions align with the schema and cover all 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 the tool's purpose: applying or discarding multiple suggestions at once, identifying the specific resource (Autopilot/repository-sync suggestions) and the action. It distinguishes itself from single-suggestion tools by emphasizing 'multiple' and 'at once'.

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 specifies when to use the tool (for multiple suggestions) and provides important prerequisites (IDs from list-space-suggestions, Enterprise access for bulk apply). It does not explicitly name the alternative single-suggestion tools, but the context implies them.

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 the description confirms this by stating it is a 'destructive action' and explains the effect (removes the invitation so it can no longer be accepted). This adds context beyond the annotation, but the core safety information is already captured by the annotation. No contradiction, but the description does not introduce substantial new behavioral details beyond confirming the destructive nature.

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

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

Two sentences, no fluff. The purpose is stated first, followed by the effect and a caution about timing. Every word earns its place, and it is easy to scan.

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 destructive tool with one parameter and annotations covering destructive behavior, the description covers when to use, what it does, and how to obtain the parameter. No output schema is present, but that is typical for a destructive action, and the description provides sufficient information 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 schema description already provides clear meaning for invitation_id (numeric pending team invitation ID) and even suggests a lookup method when given an email. The description itself does not add further parameter semantics, but the schema is fully descriptive with 100% coverage, so the baseline is 3; the extra hint about using list-team-members elevates it to 4.

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

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

The description clearly states the tool cancels a pending team invitation, using specific verb (cancel) and resource (team invitation). It distinguishes itself from sibling tools like invite-team-member or remove-team-member by explicitly targeting pending invitations before acceptance. The phrasing is unambiguous and not a tautology.

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

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

It explicitly says when to use: when the user wants to cancel a pending invitation before acceptance. It also provides a concrete prerequisite in the parameter description, directing the agent to call list-team-members first when given an email, which prevents misuse and clarifies the workflow.

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, and openWorldHint=true, so the safety profile is partly given. The description adds genuinely new context beyond that: authorization is required, changes are state-changing, children are copied along with the item, and copies landing in a public target Space are publicly accessible. It could still note that source items are left intact, but the added disclosure is substantive.

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 tight three-sentence block: trigger first, then behavioral implications, then the parameter summary. Every sentence carries information, though the trailing parameter list is somewhat redundant with the 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 4-parameter mutation tool with no output schema, the description covers the trigger, the mutation semantics, the authorization requirement, the public-visibility consequence, and the parameter set. The main remaining gap is behavior on name collisions or partial-copy failure, which is minor.

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

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

Schema description coverage is 100%, so all four parameters are already documented with their roles (source, target, parent/root). The description only restates the required/optional split and adds no syntax or constraint details beyond the schema, which is the expected baseline at full 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 gives a specific verb (copy/duplicate/clone) plus the resource (Space page/document, folder, external link, and its children) and the destination (another Space). It is clearly distinguishable from siblings like move-space-item, create-space-item, and update-space-item.

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?

"Use this when the user wants to copy, duplicate, or clone..." gives an explicit trigger condition, which is strong. It stops short of naming alternatives (e.g., move-space-item for relocating instead of duplicating), so the routing guidance is clear but not fully comparative.

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 explicitly states 'Read-only: returns grouped counts without changing suggestions or documents,' which directly aligns with the readOnlyHint and destructiveHint annotations. It goes beyond the annotations by clarifying no mutations occur to suggestions or documents, providing excellent transparency.

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

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

The description is two sentences long, front-loaded with the primary use case ('Use this when the user asks how many'), followed by behavior and optional filter. No redundant words or unnecessary details are present.

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 counting tool, the description fully covers purpose, trigger conditions, behavior, and parameter semantics. The absence of an output schema is acceptable since the return type (grouped counts) is implied by the description, and no other context is needed 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 single parameter space_id is described as 'Optional Space filter' in the schema, and the tool description adds 'numeric' and 'filter by' context, making its type and purpose unambiguous. Full parameter coverage is achieved with additional clarifying detail.

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

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

The description clearly states the tool returns grouped counts of suggestions by status (pending, snoozed, done, etc.) and identifies the resource as Autopilot/repository-sync suggestions. It distinguishes itself from list-oriented siblings by emphasizing counts rather than detailed listings.

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 states when to use this tool: 'when the user asks how many' suggestions in various states. It also mentions the optional space_id filter, giving clear guidance on invocation conditions. While it doesn't name alternative tools, the condition is specific enough to avoid confusion with list-space-suggestions.

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 states this is a state-changing action that creates and returns a signed public share link after authorization, which aligns with annotations (readOnlyHint=false). It does not mention edge cases like whether repeated calls create new links, but annotations plus the explicit creation wording provide adequate transparency.

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

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

The description is two sentences, direct, and free of redundant filler. It packs the main purpose, side effects, and required context 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?

There is no output schema, but the description clearly states that the return value is a signed public share link. It also mentions authorization, ownership restrictions, and optional expiration, which cover key operational context despite not detailing error cases or response format.

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

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

Schema descriptions cover 100% of parameters, and the tool description adds context that generation_id must be owned and come from list-generations. However, expiration semantics are only restated from the schema without additional clarification beyond the allowed values and default.

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 action: share an existing generated output, generation, or result via a public URL, and explicitly says it creates and returns a signed public share link. It also distinguishes from sibling tools by requiring an owned generation_id from list-generations.

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 explains when to use the tool (user wants to share a generation through a public URL) and mentions required ownership via generation_id from list-generations. It does not explicitly name alternative tools, but the context of generation_id makes the 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 readOnlyHint=false and destructiveHint=false, so the mutation profile is covered. The description adds genuinely new context: creation happens after MCP client authorization, and setting is_public=true makes the Space publicly accessible, which is a non-obvious side effect worth surfacing.

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, front-loaded with the trigger condition and followed by the behavioral notes. Efficient and scannable, with the key state-changing warning placed prominently; only slight redundancy in re-listing the parameters.

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

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

For a mutation tool with no output schema, the description covers the trigger, the authorization gate, the required name, and the public-visibility consequence. It omits what the response returns (e.g., new Space identifier), but that is a minor gap given the absence of an output schema.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description restates the same fields (name required, description/visibility/slug optional) without adding syntax, constraints, or format guidance beyond the structured data, so baseline 3 applies.

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

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

States a specific verb (create) and resource (documentation Space / knowledge base container), and clarifies it produces the container itself rather than a document or item, which separates it from create-space-document and create-space-item. Clear, though it does not explicitly name those 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?

"Use this when the user wants to create a new documentation Space" gives a clear triggering condition, which is the correct framing for a create tool. It provides no exclusions or named alternatives (e.g., update-space for existing Spaces), so it stops short of the top tier.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is partly given. The description adds non-structured value: that creation happens immediately 'after authorization' (an auth prerequisite) and that content in a public Space becomes publicly accessible (a visibility consequence the agent should warn about). It could say more about overwrite/duplicate-title 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?

Three short sentences, front-loaded with the trigger condition, then the state-changing warning, then the disambiguation. No filler sentences and no redundancy against the structured fields.

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 non-idempotent mutation tool with no output schema, the definition covers the trigger, the alternative, the auth requirement, and the public-visibility consequence, which is enough to invoke it safely. Minor gaps remain around what is returned and behavior on duplicate titles or existing paths.

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

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

Schema description coverage is 100%, including the 'Call list-spaces first' hint for space_id and the folder-creation side effect for path. The description's mention of 'numeric space_id, title, and markdown content' merely restates the required fields already documented in the schema, adding no syntax or format detail beyond it. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('create a markdown document/page in a Space from provided content') and explicitly routes the agent away from the closest sibling by naming create-space-item for folders or external links. An agent can distinguish this from create-space-item, update-space-document, and the generate-* family without opening schemas.

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?

'Use this when the user wants to create a markdown document/page in a Space' gives a clear trigger, and the closing sentence names the alternative tool and the condition that selects it. It lacks explicit exclusion guidance against the many sibling generation/documentation tools, but the primary fork (document vs folder/link) is covered.

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 openWorldHint=true, so the write nature is known; the description adds genuinely new context by noting creation happens directly after authorization and that content in a public Space becomes publicly accessible. This visibility consequence is meaningful behavioral disclosure beyond the structured fields. It stops short of describing return values or failure modes.

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

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

Two compact sentences, front-loaded with the trigger condition followed by the behavioral caveat. No filler, though the second sentence crams mutation, authorization, and visibility into one long clause.

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 7-parameter mutation tool with no output schema, the description covers the trigger, the state-changing nature, authorization, visibility risk, and required inputs. It omits what is returned (e.g., the new item ID) and how it differs from create-space-document, which are the remaining gaps.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the type enum values and the parent_id/path null semantics. The description restates the required set (space_id, type, title) and the conditional content/external_url relation, adding only marginal value. Baseline 3 applies.

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

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

The description states a specific verb and resource ('create a Space page/document, folder, or external link inside an existing Space') and enumerates the item types. However, it does not distinguish itself from the sibling 'create-space-document', which appears to overlap substantially, so an agent cannot fully disambiguate without opening schemas.

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 trigger is stated explicitly ('Use this when the user wants to create...') along with the required inputs and the conditional 'content or URL when relevant'. No alternatives or when-not conditions are given, so routing between this and create-space-document remains ambiguous.

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 labels the action as 'state-changing' and 'creates', which accurately reflects write behavior. It also mentions 'after authorization' and the returned public link. The annotations already cover readOnly and destructive hints, and the description adds useful context about authorization and output without 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?

The description is concise, consisting of two sentences that pack purpose, usage, and behavioral details without unnecessary verbosity. It avoids redundant phrasing and gets to the point 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?

The description provides all essential context: the action, the target resource, the output (signed public share link), and necessary authorization. It also clarifies the optional expiration parameter and the owned-access requirement, making the tool's behavior fully understandable 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?

The schema descriptions cover all three parameters (item_id, space_id, expires_in_minutes) with clear explanations. The tool description reiterates them but does not add substantial new meaning beyond clarifying that expiration is optional, which is already implied by the required parameter list. Baseline of 3 is appropriate given full 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 clearly states the action: it creates and returns a signed public share link for a Space item. It specifies the resource (Space page/document, folder, or external link) and distinguishes it from sibling tools like create-generation-share-link by focusing on space items.

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

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

The description provides a clear trigger ('when the user wants to share...') and mentions prerequisites ('requires owned Space access'). It does not explicitly contrast with alternatives, but the condition 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?

The description discloses that this is a 'state-changing external action,' requires prior authorization, and needs Enterprise access. This adds useful context beyond the annotations, though it does not cover failure modes or idempotency.

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

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

The description is two focused sentences with no redundant wording. It front-loads the primary use case and includes key constraints without unnecessary 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?

The description gives enough context about authorization, state-changing behavior, Enterprise access, and the settings involved. It does not explain the return value or behavior if a link already exists, but given no output schema and clear sibling tools, it is sufficiently 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?

The schema descriptions cover all parameters, but several are terse: 'Notification channel settings' is vague, and 'Optional path filters' lacks format details. The description adds some value for trigger events and threshold range, but nested/optional parameters remain under-specified.

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 resource ('space repository link'), and distinguishes this tool from siblings like update/delete/enable by focusing on linking a repository to a Space for Autopilot sync. It clearly identifies the action and the target resource.

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 'Use this when the user wants to link an authorized provider repository,' which gives a clear trigger condition. It does not explicitly mention alternatives like updating or disabling an existing link, but the sibling names make the distinction 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 indicate readOnly=false and destructive=false; description complements with 'state-changing external action', 'after authorization', and the limitation that test dispatch is not exposed, giving useful 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?

Three concise sentences front-load the purpose, then provide prerequisite and limitation context. No fluff or redundancy.

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

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

Given the simple output (no output schema), the description sufficiently covers when to use, prerequisite, side effects, and limitations, making the tool's role clear in the broader toolset.

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

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

Schema coverage is 100% and parameter descriptions already provide the key details (event keys from list-webhook-events, HTTP/HTTPS endpoint, optional metadata). The description reinforces but does not significantly add new parameter-level 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 ('add') and resource ('webhook subscription'), and clearly distinguishes from sibling tools like update-webhook-subscription, delete-webhook-subscription, and list-webhook-subscriptions.

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

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

Explicitly says when to use the tool and instructs to call list-webhook-events first for valid event keys, providing clear prerequisite guidance and a constraint that test dispatch is not exposed.

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 readOnlyHint=false, so the safety profile is covered. The description goes further by disclosing what is actually destroyed — a manageable Space plus, notably, a public Space and its public content — and that removal happens after MCP-client authorization. It stops short of stating irreversibility or whether dependent items (documents, links) are cascaded, which is the remaining gap.

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 front-loaded sentences: the trigger condition leads, followed by the destructive scope and then the prerequisite. Content earns its place, though 'directly after the MCP client authorizes the call' is slightly verbose for the value it adds.

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 destructive tool with no output schema and annotations covering safety, the description supplies the trigger, the scope (whole Space, including public content), the exclusion, and the ID source. Adequate; only the cascade/irreversibility behavior of dependent items is left unstated.

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

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

Schema coverage is 100% and the schema already documents space_id as a numeric ID to be sourced via list-spaces with user confirmation. The description restates the source ('from list-spaces') but adds no format, range, or validation detail beyond the schema. Baseline 3 applies when the schema carries the parameter semantics.

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

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

States a specific verb+resource (delete a whole documentation Space) and explicitly distinguishes the scope from sibling tools by noting it 'should not be used for deleting individual pages' — routing the agent away from delete-space-document/delete-space-items. An agent can separate it from the other delete-* siblings without opening any schema.

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

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

Gives an explicit when-to-use condition ('when the user explicitly wants to delete a whole documentation Space'), an explicit when-not ('not for deleting individual pages'), and a prerequisite ('Requires numeric space_id from list-spaces'). Alternatives and the selecting condition are both named.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context beyond them: deletion happens directly after authorization and removes the content from public Space areas. It does not cover reversibility or failure modes, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the usage condition and the destructive warning, with no filler or repetition of the tool name.

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

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

For a two-parameter destructive tool with full schema coverage and annotations covering the safety profile, the description supplies everything an agent needs: trigger condition, alternative tool, and authorization 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 coverage is 100%, so both parameters are already documented in the schema; the description only adds where to obtain the document ID (list-space-documents or search results), which is a helpful but marginal addition over the structured 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?

States a specific verb and resource ('delete one existing Space document/page') and scopes it to a single item, which an agent can distinguish from sibling delete-space-items without opening either schema.

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

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

Gives an explicit trigger condition ('when the user explicitly wants to delete one existing Space document/page') and routes the alternative case (folders or bulk deletion) to delete-space-items by 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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value on top: deletion happens 'directly after the MCP client authorizes the call' and may affect items 'publicly visible in a public Space.' It omits reversibility/recovery guidance, which keeps it below a 5.

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

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

Three sentences with no filler, and the trigger condition is front-loaded ahead of the destructive-action warning and the parameter note. Slightly dense but every sentence carries distinct information.

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

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

For a destructive bulk-delete tool with complete schema coverage and annotations, the description covers the trigger, the destructive/authorization behavior, the public-visibility risk, and ID sourcing. No output schema exists, so return-value explanation is unnecessary; only recovery/irreversibility detail is missing.

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

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

Schema coverage is 100%, so both parameters are already documented; that sets a baseline of 3. The description adds sourcing meaning beyond the schema by telling the agent item_ids should come from list-space-documents, which is useful invocation guidance not present in the structured 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?

States a specific verb (delete) and the full resource scope (Space pages, documents, folders, external links), including the bulk 'one or more' nature. This distinguishes it from single-item siblings like delete-space-document and from delete-space, so an agent can route correctly without opening a 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?

Opens with an explicit trigger ('Use this when the user wants to delete...') and names the exact item types in scope, plus a pointer to list-space-documents for obtaining IDs. It lacks an explicit when-not statement (e.g., versus delete-space-document), so it stops short of the top score.

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 explicitly labels the action as destructive, notes that it deletes the link after authorization, and warns that provider webhook configuration may be removed. This aligns with the destructiveHint annotation and goes beyond 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?

The description is compact and information-dense, with no filler. It covers purpose, effect, prerequisites, and required parameters in two sentences.

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

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

The description provides sufficient context for a destructive deletion operation, including permissions and side effects. It does not describe the response format, but given the absence of an output schema and the straightforward nature of the action, this is not a significant 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?

Both parameters are fully described in the schema with types and usage guidance. The tool description also references space_id and link_id, and the link_id description adds practical advice to list links first.

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

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

The description clearly states the action: removing an Autopilot repository link from a Space, and distinguishes it from related operations like creating, updating, enabling, or disabling repository links.

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

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

Explicitly says 'Use this when the user wants to remove...' and includes important context about destructive effects, authorization, required permissions, and prerequisites. The parameter description also advises using list-space-repository-links first when needed.

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 goes beyond the destructiveHint annotation by explaining the action is destructive, requires authorization, and mentions that webhook test dispatch is not exposed. This gives the agent a clear understanding of side effects and 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 two sentences, concise, and directly addresses purpose, usage prerequisite, and side effects without any redundant content.

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

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

For a tool with one parameter and no output schema, the description covers the primary purpose, a necessary prerequisite for the parameter, and the destructive nature of the operation. It is sufficiently complete 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 single parameter subscription_id is described in the schema as 'Webhook subscription ID.' The description adds that it should be obtained from list-webhook-subscriptions, which provides helpful sourcing context beyond the schema.

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

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

The description clearly states the tool's purpose: removing a webhook subscription or stopping event delivery. It uses a specific verb 'remove' and provides a clear user intent scenario, making it easy to distinguish from creation or updating webhook tools.

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

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

It explicitly states when to use the tool and notes that subscription_id should come from list-webhook-subscriptions, providing a practical prerequisite. It does not explicitly compare against alternatives like update-webhook-subscription, but the guidance is sufficient for correct usage.

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 openWorldHint=true, yet the description adds real behavioral context: this is a 'Destructive external-provider state change', it attempts webhook removal after authorization, and it stops provider events from reaching Autopilot. It also discloses the prerequisites — Enterprise access and manageable Space permission — which an agent needs before invoking a destructive, open-world operation.

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 load: trigger condition, behavioral/destructive effect, and prerequisites. The user-intent trigger is front-loaded, and 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 2-parameter, no-output-schema mutation tool, the description covers what an agent needs: when to call it, that it is destructive and touches an external provider, the authorization prerequisites, and the required IDs. Nothing material is missing.

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

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

Schema description coverage is 100%, so both space_id and link_id are already documented in the schema with types and a pointer to list-space-repository-links. The description only restates the parameter names as prerequisites, adding no format, constraint, or ID-discovery detail beyond the schema — the baseline 3 for a fully-covered schema 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?

States a specific verb (disable) and resource (Autopilot repository link for a Space), and enumerates user-facing synonyms (pause, turn off) that map intent to the tool. It is clearly distinguishable from siblings enable-space-repository-link, update-space-repository-link, and delete-space-repository-link.

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 opening clause gives an explicit trigger condition ('Use this when the user wants to pause, turn off, or disable...'), which is strong selection guidance. It stops short of naming the alternative tools (enable/delete) or stating when NOT to use this one, so it is clear context rather than full when/when-not routing.

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

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

The description transparently states it is a 'Destructive state-changing action' that 'marks the pending suggestion discarded directly after authorization.' This goes beyond the destructiveHint annotation by specifying the exact effect and timing.

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 concise at two sentences, front-loaded with the primary use case, and clearly structured with the action, effect, and requirement.

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 simple single-parameter input and no output schema, the description provides all necessary context: when to use, what it does, the destructive nature, and the source of the required ID. No additional information is needed.

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 already covers the parameter with a clear description and 100% coverage. The main description reinforces this with 'Requires suggestion_id from list-space-suggestions,' adding practical guidance on sourcing the ID, but does not exceed the schema significantly.

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

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

The description clearly states the action: 'reject, dismiss, remove from review, or discard one ... suggestion'. It specifies the resource as a documentation suggestion and distinguishes from siblings by emphasizing 'one' suggestion, contrasting with bulk or snooze operations.

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

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

Explicitly says 'Use this when the user wants to reject, dismiss, remove from review, or discard one...' and provides a prerequisite: 'Requires suggestion_id from list-space-suggestions.' It does not explicitly mention alternatives like bulk or snooze, but the word 'one' implies the scope.

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?

Description discloses that it is a state-changing action, that it enables the link and registers a provider webhook after authorization, and lists required permissions (Enterprise access, manageable Space permission, provider access). This goes beyond the annotations (readOnlyHint false, destructiveHint false) by detailing side effects and permission needs.

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?

Description is concise and well-structured, covering purpose, when to use, side effects, and permissions in two sentences 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?

Given the tool's moderate complexity (state-changing, external provider integration, permission requirements), the description provides sufficient context for correct invocation. No output schema exists, so no need to describe return values. It also clearly distinguishes from sibling enable/disable tools.

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

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

Schema covers both parameters (space_id, link_id) with clear descriptions. The tool description mentions them but adds no extra meaning beyond confirming they are required. Baseline score of 3 since schema coverage is 100% and no additional parameter info is provided.

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 clearly states the verb 'enable' and the resource 'repository sync link' for a Space, and distinguishes from sibling tools like disable, create, update, and delete by specifying 'turn on or resume an existing' link.

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

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

Explicitly says when to use this tool ('when the user wants to turn on or resume an existing...'), which directly contrasts with sibling tools like create or disable. It implies not for new links, and the requirement for 'existing' differentiates it clearly.

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 reinforces the readOnlyHint annotation by stating 'Read-only: returns merged Markdown without changing Space content,' adding specific behavioral details about the output and side effects. No contradictions 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 concise, consisting of three focused sentences with no redundant information. Each sentence adds value: purpose, read-only behavior, and alternative usage guidance.

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 self-contained for the tool's simple scope: it explains the input (selected items), the output (merged Markdown), the side effects (none), and provides differentiation from related workflows. It does not require additional context to be used 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?

Both parameters (space_id and item_ids) have descriptions that clarify their meaning and role, and schema coverage is 100%. The descriptions are clear, though they could provide more detail about constraints or formats, but they adequately cover the semantics.

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

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

The description clearly states the tool's purpose: exporting selected Space pages, folders, or docs as Markdown. It specifies the verb 'export' and the resource type, and distinguishes from other tools by mentioning the MCP response and browser guidance for other export flows.

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 states when to use the tool ('when the user wants a Markdown export') and when not to ('Use browser guidance for PDF, ZIP, or download-only export flows'), providing clear guidance on alternative approaches.

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 openly discloses that this is a state-changing action, consumes AI credits, creates a generation, and writes a document to the specified space_id. This goes beyond the annotations and gives the agent a clear picture of side effects before invocation.

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

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

The description is two concise sentences, front-loads the primary use case, and includes key side effects without unnecessary wording. Every sentence adds meaningful 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?

Given the tool has 9 parameters and no output schema, the description provides essential context: when to use it, what it produces, and what side effects it has. It does not describe the return value or explicitly contrast sibling tools, but the schema covers parameters and the core behavior is sufficiently contextualized.

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

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

Schema coverage is 100% and every parameter already has a detailed description, including the instruction to call list-spaces first for space_id. The tool description itself does not add extra parameter-level meaning, but the schema already carries the weight, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: use it when source files are supplied and generated documentation should be saved directly into an existing Space. It names the action, target resource, and outcome, and it is implicitly distinct from plain generation tools by emphasizing the direct write to a space.

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

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

The description gives an explicit 'use this when' condition: when the user supplies source files and wants documentation saved directly in an existing Space. It does not mention when to prefer an alternative tool, such as add-generation-to-space, but the primary usage scenario 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?

The description fully discloses side effects: it is a 'state-changing action' that 'consumes AI credits, creates a private Space, links the repository, and queues per-file jobs.' This aligns perfectly with the annotations (readOnlyHint=false, destructiveHint=false) and leaves no hidden consequences for the agent.

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 main description is a single, dense sentence that conveys the action, prerequisites, side effects, and core parameters without any fluff. The parameter descriptions are equally succinct yet informative, making the entire tool definition highly efficient.

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

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

The description covers the essential context: when to use, what it does, side effects, and key inputs. It does not include an output schema, so no return value is needed. However, it omits any mention of what the user will see after the call (e.g., a Space ID or job status), which could be helpful but is not strictly required given the lack of output schema.

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

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

Schema description coverage is 100%, but the parameter descriptions go beyond basic definitions. For example, repository_id explicitly warns against passing slugs or URLs, and selected_files clarifies that the tool creates one Space with per-file queued docs and suggests browser guidance when files are not yet chosen. This adds practical value beyond the raw schema.

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

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

The description clearly states the tool's purpose: creating a new documentation Space from selected files in an imported repository. It uses a specific verb ('creates') and distinguishes this tool from siblings like generate-code-documentation by emphasizing the Space creation and per-file queued jobs based on selected_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 explicitly opens with 'Use this when the user wants a new documentation Space built from selected files in an imported repository,' providing a clear condition. It also notes 'After authorization' as a prerequisite and warns about credit consumption, but it does not explicitly mention alternative tools when the user wants different outputs (e.g., full-tree vs. selected files), so it's not fully exhaustive.

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 is state-changing, consumes AI credits, creates a generation, and only returns commented code after authorization. This goes beyond the annotations by explaining side effects and prerequisites.

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 concise and front-loads the primary use case. The final 'Use browser guidance for file uploads' sentence is a minor extraneous addition that does not clearly connect to the core behavior.

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

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

With no output schema, the description appropriately states that it returns commented code after authorization and notes credit consumption. It is complete enough for an agent, though authorization details are not elaborated.

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 already fully describes all three parameters with clear descriptions, so the description adds little extra semantic value. It does not elaborate on how filename affects behavior beyond identifying the file path.

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 action (adding inline comments, docblocks, docstrings, or annotations) and the resource (user-supplied source code), with explicit trigger language. This distinguishes it from related documentation/test-generation tools even without naming them.

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 provides an explicit 'Use this when...' trigger covering the relevant user requests. However, it does not explicitly contrast with sibling tools such as generate-code-documentation or generate-code-tests, leaving some alternative-selection nuance implicit.

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 only flag readOnlyHint=false, openWorldHint=false, destructiveHint=false. The description adds materially useful behavior beyond those: it is state-changing, consumes AI credits, creates a generation, and returns documentation only after authorization. These disclosures (costs, side effects, auth requirement) are exactly the kind of context annotations don't carry. No contradiction 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?

Three sentences with the primary purpose front-loaded and no filler. The 'Use browser guidance...' sentence is efficient but slightly cryptic jargon. Overall the description is appropriately sized and every sentence carries 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 description covers purpose, side effects (credits, authorization), and a usage boundary, which is good. However, given a very large sibling set with several near-identical generators (generate-codebase-documentation, generate-full-tree-documentation, generate-repository-documentation), sharper differentiation would help. It also gives minimal return-value detail despite there being no output schema.

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

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

Schema description coverage is 100%, so the schema fully documents all 5 parameters; the baseline is 3. The description's mention of 'document one or more files' loosely echoes the files parameter but adds no syntax, format, or constraint detail beyond what the schema already provides. It does not compensate for or extend the schema in any meaningful way.

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

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

The description states a specific verb and resource ('generate markdown documentation' for user-supplied source code) and the trigger condition ('asks to... explain code, or document one or more files'). It signals a per-file/multi-file scope and separates that from repository/full-tree flows, which helps an agent distinguish it from siblings like generate-repository-documentation and generate-full-tree-documentation, though it never names 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?

It opens with 'Use this when the user supplies source code and asks to generate markdown documentation...' and closes by steering local-upload and repository/full-tree flows to browser guidance. This gives clear invocation conditions and an explicit exclusion, but it doesn't name the specific sibling tools to fall back on, 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the action is state-changing, consumes AI credits, creates a generation, and returns revised code. It also mentions 'After authorization,' adding a prerequisite. This provides valuable behavioral context not covered by annotations, though it does not detail error handling or reversibility, which are minor gaps.

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

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

The description is two sentences long, with the usage condition front-loaded in the first sentence and behavioral details in the second. There is no filler or redundancy; every clause adds value. It is appropriately sized and structured.

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 five parameters and no output schema, the description covers key aspects: when to use, side effects (credits, generation creation), and return value (revised code). It does not explicitly mention the format of the return or potential failure modes, but the schema covers parameters and the description gives enough context for an agent to invoke it correctly. Given the complexity, it is mostly 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 100%, with all parameters already described meaningfully (e.g., source_code, filename, optimization_focus). The tool description does not add any extra parameter semantics beyond what the schema provides. Since the schema covers parameters thoroughly, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to generate an optimized or refactored version of supplied source code. It uses a specific verb ('optimize') and resource ('source code'), and explicitly distinguishes it from sibling tools by specifying the trigger condition: when the user asks for optimization/refactoring. This sets it apart from code-comments, tests, and documentation generators.

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 opens with 'Use this when the user supplies source code and asks for an optimized or refactored version,' providing a clear condition for when to invoke it. It also mentions 'After authorization,' implying a prerequisite. However, it does not explicitly mention alternative tools or when not to use it, though the trigger is specific enough to avoid ambiguity among 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?

The description discloses that this is a state-changing action, consumes AI credits, creates a generation, and returns test code only after authorization. This adds meaningful context beyond the annotations (readOnlyHint=false, destructiveHint=false), which only say it is not read-only and not destructive. The description does not conflict 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 three short, purposeful sentences: one scoping when to use, one stating behavioral consequences, and one offering guidance for edge cases (local uploads, repo-wide). No filler or redundant phrasing.

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

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

With no output schema, the description explains that the tool returns test code after authorization, which is a helpful summary. Given the 6 parameters are all documented in the schema and the tool's complexity is moderate, this is complete enough for an agent to call it correctly, though it could mention what happens if authorization is not granted.

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

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

Schema description coverage is 100%, so each parameter is already well-documented by the input schema (e.g., source_code, test_type, test_framework). The description adds no extra parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific action (generate tests) with a specific resource (source code) and enumerates the kinds of tests (unit, feature, integration, framework-specific). It is immediately distinguishable from sibling tools like generate-code-comments, generate-code-documentation, and generate-code-optimization because it focuses exclusively on test-generation.

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

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

Provides a clear when-to-use condition: 'when the user supplies a URL to additional 4 test-generation of unit, feature, integration, or framework-specific tests.' It lacks explicit exclusions (e.g., don't use for comments or documentation), but the purpose statement indirectly differentiates from 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?

The description discloses key side effects: it is state-changing, consumes AI credits, creates a private linked Space, and queues documentation. It also notes authorization is required. These go beyond the annotations, which only indicate non-read-only and non-destructive, giving the agent a clear picture of consequences.

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 concise and well-structured, conveying the trigger, action, and key parameters in two sentences. No redundant words or vague filler. It front-loads the main purpose and follows with necessary 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?

Given the moderate complexity (four parameters, side effects, and a preview dependency), the description is largely complete. It mentions authorization, side effects, and the preview hash matching requirement. It does not describe the output or post-queue behavior, but no output schema exists and this information is not critical for invocation.

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

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

The schema descriptions already cover all parameters clearly. The main description adds context by explaining that repository_id and accepted_tree_hash come from the stored preview, reinforcing their roles. It also clarifies that excluded_paths is metadata only, which is helpful. Slight room to tie parameters more explicitly to the workflow, but overall strong.

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 explicitly states the tool's purpose: to create a documentation Space after a preview is reviewed. It names the specific resource (Space) and the action (create/queue docs), and clearly ties to the preview workflow. This distinguishes it from other generation tools that don't create Spaces.

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

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

It gives a clear condition: 'Use this when the user has reviewed a full-tree preview and asks to create its documentation Space.' This implies the correct timing and context. It stops short of explicitly mentioning alternatives, but the precondition is specific enough to guide selection among similar 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely useful context beyond them: it requires authorization, consumes AI credits, creates a generation, returns converted code, and warns that results saved to public Spaces are exposed. That is substantial behavioral disclosure.

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, front-loaded with the triggering condition and zero obvious padding. It is appropriately sized for the tool's complexity, though the saving/public-Space clause 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?

For a state-changing, credit-consuming generation tool with no output schema, the description conveys the essential lifecycle: authorization, credit cost, output (converted code), and persistence semantics. Only minor gaps remain (e.g., no failure/format details), but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including the nested save_to_space object. The description only restates the four required inputs without adding syntax, format, or constraint detail, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: converting a single supplied source-code file to another programming language or framework. This is clear and distinguishably different from documentation/optimization siblings. It stops short of naming any specific alternative tool, so it doesn't fully earn 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?

It gives a clear trigger condition ('when the user supplies one source-code file for conversion'), which implies usage. However, it names no alternatives and gives no when-not-to-use guidance among the many generate-* siblings, leaving selection 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 cover the safety profile, and the description adds genuinely new context: this is a state-changing action that consumes AI credits and may make output publicly accessible via Space saving. That is real disclosure beyond what readOnlyHint/destructiveHint provide, though rate limits and failure behavior are unstated.

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 side effects. It is dense and clause-heavy but every clause carries a fact; no filler.

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

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

For a six-parameter, nested-object, no-output-schema tool, the description covers the triggering scenario, required inputs, auth requirement, credit consumption, and public-visibility risk of the optional Space save. Quite complete, with only alternative-selection guidance missing.

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

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

Schema description coverage is 100%, so all six parameters are already documented in structured fields; the description's mention of numeric repository_id and selected_files only restates the schema. Baseline 3 is correct since the schema does the heavy lifting.

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

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

The description gives a specific verb+resource+scope: 'one markdown document generated from selected files in an imported repository.' That distinguishes it from broad siblings like generate-codebase-documentation or generate-repository-readme by scoping output to selected files, though it never names a sibling 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?

It states the triggering condition ('Use this when the user wants one markdown document...') and prerequisites (authorization required, credits consumed). It does not, however, say when NOT to use it or which alternative to pick for readme/release-notes style output.

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

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

Goes well beyond the annotations by disclosing that authorization is required, that it is state-changing, that it consumes AI credits, that it creates a generation, and that saving to a Space may make the output publicly accessible. This is exactly the kind of cost/side-effect context an agent needs before invoking.

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, and the second sentence packs the side-effect profile efficiently. It is dense but each clause carries information an agent needs.

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

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

For a state-changing, credit-consuming tool with no output schema and a nested parameter object, the description covers triggers, authorization, cost, and public-exposure risk. It does not indicate the return value (e.g., a generation identifier) or whether generation is asynchronous, a minor remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including the nested save_to_space object and the license/sections dependency. The description only restates that repository_id must be numeric, adding little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (generate/refresh) and resource (README for an imported repository), so an agent can distinguish it from the generic documentation generators. It stops short of naming sibling alternatives such as generate-repository-documentation or generate-and-add-documentation, which is the only gap.

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

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

Gives a clear trigger condition: 'Use this when the user asks to generate or refresh a README for an imported repository.' It sets the precondition that the repository must already be imported, but offers no explicit when-not or alternative-tool routing.

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

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

The description discloses important side effects: it is state-changing, consumes AI credits, creates a generation, and can optionally save to a Space after authorization. These align with the annotations (readOnlyHint false, destructiveHint false) and no contradiction is present.

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

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

The description is concise and information-dense, covering the trigger condition, side effects, and optional output in one sentence. There is no redundant or filler content.

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

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

The description fully covers how to invoke the tool and what side effects occur, but it does not explicitly describe the return value or generation object. Since there is no output schema and the tool creates a generation that can later be retrieved via sibling tools, a brief note about the return would make it slightly more 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?

The schema already covers all 7 parameters, and the descriptions add meaningful context such as provider examples (GitHub, GitLab, Bitbucket, Azure DevOps), branch examples, and the Space destination requirement. This goes beyond the raw schema and helps the agent map user intent to the correct parameter values.

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: generating release notes by comparing two branches of a connected provider repository. It clearly distinguishes this tool from sibling generation tools like generate-repository-documentation or generate-code-documentation by focusing on branch-to-branch release notes.

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

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

It explicitly says when to use the tool ('when the user wants release notes from two branches') and notes prerequisites like a connected provider repository and authorization. It does not explicitly mention when not to use it or name an alternative tool, but 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 only tell the agent this is a non-read-only, open-world, non-destructive call. The description adds meaningful specifics the annotations cannot convey: authorization is required, AI credits are consumed, a generation record is created, the return is OpenAPI JSON, and saving to a Space may make the output publicly accessible. That public-exposure warning is high-value disclosure for a state-changing action.

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 dense sentences with no filler: the usage trigger is front-loaded, followed by side effects and I/O shape. Every clause (auth, credits, mutation, return type, file paths, public Space) carries distinct 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?

Though there is no output schema and the tool has six parameters including nested objects, the description covers the missing pieces an agent needs: invocation trigger, authorization, credit cost, mutation side effect, return type, and the public-visibility caveat for Space saves.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds framing beyond the schema by explaining the one-file versus multiple-files duality ('accepts one source_code file or multiple files entries') and the Space destination, which helps an agent pick the right parameter path even though the per-field semantics live in the schema.

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

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

States a specific verb and artifact: generate an OpenAPI/Swagger specification from supplied API source code, and even names the input form (source_code file or multiple files) and the return (OpenAPI JSON). This clearly separates it from the many sibling generate-* tools (UML, README, tests, comments) by input and output.

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?

Opens with an explicit trigger condition ('when the user supplies API source code and asks for an OpenAPI or Swagger specification') and routes between the single-file and files[] paths. It hints at an alternative for local uploads ('use browser guidance for local uploads') but does not fully state when-not to use it or name a specific sibling alternative.

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

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

Goes well beyond the annotations by disclosing that it consumes AI credits, requires authorization, creates a generation, and can persist markdown to a Space with public exposure implications. This is valuable cost/side-effect context for a write tool, though reversibility and rate limits are not stated.

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 front-loaded sentences: trigger, behavioral consequences, and a boundary note. Dense with little waste, though the final sentence ('Use browser guidance...') is under-specified for the space it occupies.

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?

No output schema exists, yet the description covers trigger, cost, side effects, and persistence/sharing outcomes. A complex nested-parameter mutation tool would benefit from naming related read tools like get-generation or list-generators, but the essentials are present.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the nested save_to_space object. The description adds only marginal mapping ('markdown to a Space' for save_to_space) and no format or constraint detail beyond the schema, so the baseline 3 holds.

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 (generate) plus resource (UML diagram) and enumerates the diagram flavors (Mermaid, sequence, class, component, architecture) it covers. An agent can distinguish this from the many sibling generate-* tools (documentation, tests, comments) without opening a 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?

Gives a clear trigger condition: the user supplies source code and asks for UML/diagram output. It also points elsewhere for out-of-scope cases ('browser guidance for local uploads or full-repository diagrams'), though that reference is vague and no sibling generator is named for direct comparison.

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 readOnlyHint annotation already establishes safety, and the description reinforces it by stating 'Read-only' and clarifying that it returns preferences 'without changing settings.' It adds useful context about the return value being effective personal/team preferences and editability, going slightly beyond the bare 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 two sentences with zero wasted words, front-loaded with the 'Use this when...' trigger. Every clause earns its place, covering purpose, side-effect profile, and return semantics 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?

There is no output schema, but the description covers the return content ('returns effective personal/team preferences and whether they are editable'). For a simple parameterless read tool, this is complete: the agent knows when to call it, what it does, and what it returns.

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 there is nothing to document. Per the baseline for 0 params with full schema coverage, the score is 4.

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

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

The description states a specific verb ('view') and specific resources ('AI writing guidelines, templates, strict mode, generator scope, or team-enforced generation preferences'), making the purpose clear. It distinguishes itself from sibling tools implicitly through the read verb contrasting with update-ai-preferences, though it does not explicitly name any alternative.

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

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

The description gives an explicit trigger condition ('Use this when the user wants to view current...preferences') that tells the agent when to invoke this tool. It does not explicitly contrast with update-ai-preferences or other siblings, but the read-versus-write boundary is reasonably clear 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?

The description reinforces the read-only nature stated in annotations and adds useful context by mentioning that it returns credit impact, which is a potential cost consideration. No contradictions exist, and the additional detail is valuable given the annotation coverage.

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 with no unnecessary words. It efficiently conveys purpose, usage context, and return contents.

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-only tool with one parameter and no output schema, the description provides sufficient context: when to use it, what it returns, and the fact that it is non-destructive. No critical information 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 schema description already fully documents the single parameter (repository_id) with clear guidance on what to pass and what not to pass. The tool description only repeats 'numeric repository_id' without adding extra meaning, so it meets the baseline for high 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 clearly states the tool's purpose: to inspect an existing full-tree documentation preview. It uses the specific verb 'inspect' and identifies the resource type. It also distinguishes itself from related tools like generate-full-tree-documentation by focusing on previewing rather than generating.

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 provides a 'when to use' condition: when the user wants to inspect an existing preview before creating a Space. However, it does not explicitly name alternative tools or state when not to use it, leaving some inference to the agent.

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=true and destructiveHint=false, and the description restates 'Read-only' and 'without changing it' — which is redundant but not harmful. The description does add that it 'returns the generation by numeric generation_id', a small behavioral detail (the return object is the generation), but no extra side effects, permissions, or limits are disclosed beyond what the annotations already imply. With annotations carrying the safety profile, the additional value here is minor.

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 efficiently worded in two sentences totaling less than 50 words. The first sentence front-loads the primary usage cases; the second adds the read-only guarantee. It is slightly redundant with the annotations ('read-only', 'without changing it'), but that redundancy is short and does not distract. No fluff; each clause serves the task.

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 no output schema, the description gives only a high-level return ('returns the generation') and says it includes 'generated markdown' and 'version metadata' in the trigger context. It does not fully specify the return shape (e.g., which fields of the generation object are returned), nor does it mention pagination or any error conditions. Given the tool's simplicity and full schema coverage, this is adequate but leaves the exact response payload partially unexplained, which matters because there is no output schema to fill the gap.

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

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

The schema description coverage is 100%: generation_id is described as 'The numeric generation ID. Call list-generations first' and include_source as 'Include the original source code/content. Defaults to false.' The description adds a phrase 'inspect version metadata, see generated markdown' which loosely hints at what include_source might affect, but it does not go beyond the schema's explicit parameter descriptions. Baseline 3 applies because the schema already does the heavy lifting.

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

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

The description uses a specific verb 'read' and a specific resource ('a specific generated output/result', 'generation'). It distinguishes this tool from siblings like list-generations (listing) and update-generation (mutating) by emphasizing a single read-only fetch — 'read a specific generated output', 'returns the generation by numeric generation_id' — and by naming the target. The scope and intent are unambiguous.

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 states the conditions for use: 'when the user wants to read a specific generated output, inspect version metadata, see generated markdown, or choose a version for later actions'. This provides a clear trigger context. However, it does not explicitly mention alternatives like list-generations or say 'not for listing' or 'not for updating', so exclusions are absent. The usage context is strong but lacks direct contrast with related 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 and destructiveHint, and the description adds valuable behavioral context: it is an Enterprise feature, returns entries newest first, and requires Enterprise access. This goes beyond the schema and annotations without contradicting them.

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

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

Two sentences, front-loaded with the use case and scope, with no wasted words. Every clause adds relevant information: when to use it, read-only nature, ordering, and requirements.

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

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

For a read-only audit log tool, the description covers purpose, ordering, required access, and the key prerequisite of calling list-spaces first via the schema. It does not describe the response format, but there is no output schema and the core call guidance is present.

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

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

Schema coverage is 100%, so the schema already documents all three parameters with descriptions. The description reinforces that space_id is numeric and that Enterprise access is required, but it adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: it returns the Space activity/audit log, newest first. It also gives concrete trigger examples (what changed, who changed settings, sync events, document actions, recent activity), which clearly distinguishes it from the many sibling tools.

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

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

The description opens with explicit guidance on when to use the tool: whenever the user asks about changes or recent activity in a Space. It also notes the Enterprise-access requirement, but it does not explicitly state when not to use it or mention alternative 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?

The description explicitly states 'Read-only: returns the selected document without changing content', matching the readOnlyHint annotation. It also notes the precondition of needing a document ID, so the agent knows it must first obtain that ID.

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

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

The description is two sentences long and directly states purpose, behavior, and prerequisite without unnecessary detail. Every sentence adds value.

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

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

The tool is simple and the description covers when to use, what it returns, and the required input context. No output schema is present, but the return value ('full markdown content') is clearly implied by the purpose.

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?

Both parameters are described in the schema with clear definitions: space_id as 'numeric ID of the space containing the document' and document_id as 'numeric ID of the document to retrieve'. The description reinforces document_id's provenance by naming the source tools.

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

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

The description clearly states the tool's verb ('read') and resource ('full markdown content of a specific Space document'). It also specifies when to use it ('after search or listing') and how it differs from listing tools by requiring a document ID from list/search/global-search.

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

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

It explicitly says 'Use this when the user wants to read the full markdown content...', providing clear trigger conditions. It also instructs that the document ID must come from list-space-documents, search-space-documents, or global-search, giving sequential 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?

The annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying exactly what is returned (account name and can_generate boolean) and reaffirms no account data changes, which is useful 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?

Two concise sentences with a clear when-to-use trigger front-loaded, followed by the return contract. No redundancy or filler, every sentence earns its place.

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

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

For a zero-parameter, read-only tool, this description is complete. It conveys the invocation trigger, the read-only safety, the exact returned fields, and the lack of side effects. No additional information is needed for an agent to call it correctly.

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

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

The tool has zero parameters and the schema coverage is 100% by default. With 0 params, the baseline is 4; the description further explains the output fields (account name, can_generate) which adds semantic understanding, even though no parameter details are needed.

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

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

The description states a specific verb and resource: returns the connected DocuWriter.ai account name and a can_generate boolean. It clearly distinguishes itself from generation-execution or other getters among the siblings by focusing on the account's connection status and generator availability.

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 'Use this when the user asks which DocuWriter.ai account is connected or whether it can run a generator,' giving clear when-to-use conditions. It does not list alternatives or exclusions, but for a simple read-only zero-parameter tool, this is sufficient 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?

The description explicitly states the tool is read-only and returns matching titles, snippets, Space details, and URLs without changing content. This goes beyond the readOnlyHint annotation by detailing the exact nature of the output and reaffirming no side effects.

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

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

The description is brief, consisting of two sentences that cover the tool's purpose, scope, read-only nature, and output contents. There is no redundant or unnecessary 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 simple search tool, the description provides complete context: what it searches, when to use it, that it's read-only, and what it returns. It sufficiently equips an agent to decide when and how to invoke it without needing additional 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?

The parameter schema already covers query and per_page with clear descriptions. The description does not add significant semantic details beyond what the schema provides, so a baseline score 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 explicitly states the tool's purpose: searching documents across all accessible Spaces. It distinguishes itself from search-space-documents by mentioning 'rather than one known Space,' making the resource and scope 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 directly instructs when to use the tool: when the user wants to search across every accessible Space. By contrast, it implies that for a single known Space, search-space-documents should be used, providing clear usage guidance.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses that it creates a pending invitation, sends one email, and requires browser-based acceptance. This adds concrete behavioral context about the external effect and flow, which annotations alone do not provide.

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

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

Two sentences with no filler. The trigger condition is front-loaded, followed by a compact behavioral summary. Every clause earns 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 simple two-parameter tool with no output schema, the description fully covers the action, its side effects, and the authorization/acceptance flow. It also hints at the need to inspect existing members via list-team-members. Nothing essential is missing 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 100%, so both parameters are already well-documented in the schema. The description repeats 'editor or viewer role' but adds no new semantic details about the parameters themselves. Per the rubric, baseline 3 applies when schema covers parameters fully.

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 specific verb and resource: inviting a teammate by email with a role. It distinguishes itself from siblings like cancel-team-invitation and remove-team-member by focusing on the invite action. The phrase 'state-changing external action' reinforces its non-readonly nature.

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 opening 'Use this when...' gives a clear trigger condition. The schema also instructs to use list-team-members first for role inspection and for identifying existing invites, which is useful. However, it does not explicitly mention when not to use it or name alternatives, though the sibling list makes it implicit.

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 and destructiveHint=false, and the description reinforces this with 'Read-only' and 'without changing anything.' It adds extra behavioral context by mentioning that the tool 'can include previews or full content,' which goes beyond the annotations. Overall, the behavior is transparent and consistent.

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 concise sentence that immediately states the usage condition and then summarizes the core functionality. There is no redundant or extraneous wording. The structure is effective, front-loading the most important guidance.

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 there is no output schema, the description provides a reasonable hint about the response by mentioning 'previews or full content.' It does not detail pagination or ordering, but those are implied by the parameters. For a simple list tool, this is adequately complete in context with the sibling tools.

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

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

Schema coverage is 100% with all five parameters described, so the baseline is 3. The description does not add any extra parameter-level detail beyond what the schema already provides. Each parameter's purpose and default are clear from the schema, but no additional semantic depth is given.

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 that the tool lists visible personal and team generations, with an explicit verb ('list') and resource ('generations'). It also differentiates from siblings like get-generation and list-generators by specifying when to use it: to find generated outputs, generation history, previous results, archived items, or IDs for later actions. This makes the purpose unambiguous and 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 explicit conditions for use ('when the user asks to find generated outputs, generation history, previous results, archived items, or IDs for later generation actions'). It also notes the read-only nature. However, it does not explicitly state when not to use it (e.g., when a single generation is needed, use get-generation), leaving some inference to the agent. Still, the guidance is strong.

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 goes well beyond the annotations by detailing the exact data categories returned (identifiers, required inputs, credit behavior, Space output behavior, browser-only setup boundaries) and explicitly stating no generator is run. Since annotations already mark readOnlyHint and destructiveHint, this richer context provides the agent a full behavioral picture.

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

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

Two sentences, both purposeful and front-loaded. The first sentence gives the usage trigger, and the second lists the key outputs and the read-only nature; no filler or repetition of schema/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?

No output schema exists, so the description compensates by listing the exact content categories an agent can expect. With zero params, no side effects, and read-only annotations, there are no other operational boundaries that need explanation for safe and 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?

There are zero parameters, so the description cannot add per-parameter meaning; the baseline for 0 params is 4. The description still usefully summarizes what kind of information the tool returns, which is the closest possible semantic content for a parameterless list operation.

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

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

Description states a clear verb ('lists') and resource (available DocuWriter.ai generators) while explicitly saying it returns generator identifiers, required inputs, credit behavior, Space output behavior, and browser-only setup boundaries. This distinguishes it from the many generate-* siblings by adding 'without running a generator' and from list-generations by focusing on available generator definitions.

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

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

It gives a specific when-to-use trigger: when the user asks which generators are available or what inputs a generator requires. It also communicates a when-not boundary through 'without running a generator' and 'Read-only', but it does not explicitly name alternative sibling tools as the get_calls calibration example does.

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?

Clearly describes the tool's read-only nature ('Read-only'), output ('returns provider status and browser-only connect/reconnect guidance'), and what it does not return ('without exposing credentials'). This goes beyond the basic information and sets proper expectations.

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

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

Two sentences with no fluff. Every word contributes value: purpose, timing, read-only nature, output, and alternatives. Highly concise and well-structured.

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?

Covers the essential context: when to use, what it does, what it returns, and its limitations. It does not mention potential error cases or what happens if no providers are connected, but for a simple read-only listing tool, the provided information is sufficient for an agent to act 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 schema descriptions cover both parameters (provider and include_guidance) with value hints and defaults, achieving 100% coverage. The tool description itself does not add extra meaning beyond what the schema provides, so it meets the baseline but does not enhance it. However, the mention of providers in the purpose gives slight context, so not a 2.

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

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

States a specific verb and resource: describes when to use (user asks whether GitHub, GitLab, Bitbucket, or Azure DevOps is connected, or asks which imported repository records exist) and distinguishes from sibling tools that list repositories or manage connections. Clear and unambiguous.

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

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

Explicitly says 'Use this when...' and provides alternative guidance: 'Use repository-link tools for Space Autopilot links.' This gives clear direction on when to use this tool versus others, leaving nothing 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?

The annotation readOnlyHint is true, and the description echoes this with 'Read-only external-provider lookup.' It also clarifies that it may return reauthorization/browser guidance, which is helpful for understanding 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?

The description is a single, focused sentence that leads with the primary use case, making it 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?

The tool is straightforward and the description covers purpose, usage context, and read-only nature. No output schema exists, so no additional return value documentation is needed.

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?

Both parameters have descriptive text in the schema, and the description adds context like the provider values and the purpose of space_id. This fully covers the 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 the tool's function: listing repositories from a connected provider for selection before creating an Autopilot link. This distinguishes it from sibling tools like list-provider-connections, which list connections rather than repositories.

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 indicates when to use it (before creating an Autopilot link) and that it fetches repository choices, but it doesn't explicitly contrast with alternatives. However, the context and the phrase 'before creating an Autopilot link' provide sufficient 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 provide readOnlyHint=true and destructiveHint=false, so the description adds marginal value by reiterating 'read-only' and 'without changing content.' It does explicitly mention what the tool returns (documents and folders), which is useful. For a simple read operation with no side effects, this level of transparency is sufficient. 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 two sentences with no fluff. The primary usage guidance is front-loaded, and the read-only constraint is stated concisely. Every sentence adds value and no information is redundant beyond the 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 tool with one simple parameter, no output schema, and clear annotations, the description covers the essential context: when to use, what it does, and what it returns (documents and folders). It doesn't mention pagination or limits, but given the simplicity and the fact that no output schema exists, the level of detail is adequate for an agent to invoke correctly.

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

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

Schema description coverage is 100%, and the parameter description already explains space_id as a numeric ID and directs to call list-spaces first. The tool description adds 'one numeric space_id' which reinforces the single-value requirement but doesn't add new semantic details. The schema carries the explanatory load, so the baseline of 3 applies.

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

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

The description states a specific set of actions (browse, list, find IDs, inspect structure) on a specific resource (Space tree, documents, folders) and explicitly notes it is read-only. It clearly distinguishes from search-space-documents (which implies search semantics) and get-space-document (single document retrieval) by covering the full tree browsing use case.

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 says exactly when to use: browsing a Space tree, listing documents, finding numeric IDs, inspecting structure before editing. It also adds the condition 'for one numeric space_id' and implies a prerequisite (call list-spaces first) via the parameter description. It doesn't explicitly name alternatives or exclusions, but the use cases are well-defined.

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 clearly states the tool is read-only and specifies what it returns (configured repository links plus bounded sync status/activity) and what it does not expose (raw provider payloads). This aligns with the readOnlyHint and destructiveHint annotations, with 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?

The description is reasonably concise, using two sentences to convey purpose, usage context, and behavioral details without unnecessary verbosity. It is slightly long but every part adds value.

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

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

The description provides sufficient context for an agent to use the tool correctly, including when to invoke it and what kind of output to expect. It does not describe output format in detail, but that is not required given the lack of an output schema and the simplicity of the 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 schema description coverage is 100%, so the parameters are well-documented. The description does not add significant extra meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states when to use the tool (when the user asks about repositories linked to a Space for Autopilot, repo sync, etc.) and what it does (returns configured repository links and sync activity). It distinguishes itself from sibling tools that create, delete, enable, or disable links.

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 gives the conditions for use ('Use this when...') and mentions the contexts (Autopilot, repo sync, suggestion generation, trigger events, recent sync activity). It does not explicitly mention alternatives or when not to use, but the intended usage is clear from the 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?

The description explicitly says 'Read-only' and 'does not change settings or documents'. This aligns with the annotations (readOnlyHint=true, destructiveHint=false). No hidden behaviors are present.

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

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

The description is a single, focused sentence with no redundant content. It is well-structured 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?

For a simple tool with no parameters and no output schema, the description sufficiently conveys the purpose, usage context, and read-only guarantee. It is complete.

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

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

The tool has zero parameters and an empty schema, so there is nothing additional to explain. The description appropriately omits parameter details.

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 that the tool lists accessible Spaces. It also specifies when to use it, particularly when the user asks to see or choose Spaces, and notes the typical use case before tools requiring a numeric space_id. This gives a distinct purpose.

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

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

It provides explicit usage instructions, saying to use it when the user wants to see or choose Spaces. It also highlights that it is especially useful before tools that need a numeric space_id. The read-only nature is stated, differentiating it from mutation 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?

The description explicitly states 'Read-only: returns suggestion inbox items and IDs ... without changing documents', which clearly communicates that the operation has no side effects. This aligns perfectly with the readOnlyHint annotation and provides the agent with a strong guarantee of safety.

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

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

The description is a single, focused sentence that conveys the purpose, safety, and typical usage without extraneous information. It is well-structured and easily parseable, making it efficient for an agent to digest.

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

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

The description covers the essential context: what the tool does, the fact that it is read-only, and how the results will be used (for later apply/discard/snooze). It does not include an output schema, but for a straightforward list operation, the information provided is sufficient for an agent to understand the tool's role and invoke it correctly.

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

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

All four parameters have descriptive names and descriptions. The status parameter explicitly lists accepted values (pending default, applied, discarded), which goes beyond a basic type definition. The space_id description includes a useful instruction to call list-spaces first, and limit/batch_id are self-explanatory. Schema coverage is 100% with meaningful additional 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 clearly states the tool's purpose: reviewing documentation suggestions for a Space. It specifies the action (review/list) and the resource (suggestions for a Space). It also distinguishes itself from related tools by noting that it returns items and IDs for later apply/discard/snooze actions, which sets it apart from siblings like count-space-suggestions or bulk-manage-space-suggestions.

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

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

The description provides a direct usage trigger: 'Use this when the user wants to review...'. It implicitly differentiates from alternatives by highlighting the returned items and IDs for later actions, but it does not explicitly mention when not to use it or compare it to similar list/count tools. This leaves a slight gap in explicit 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?

The description explicitly states 'Read-only' and 'without changing state,' reinforcing the readOnlyHint annotation. No contradiction exists.

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

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

The description is a bit long but efficiently covers multiple related intents. It is well-structured with a clear use-case list and explicit read-only disclaimer.

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 no parameters and no output schema, the description adequately covers what the tool returns (roster, invitations, roles, capabilities). It provides enough context for an agent to decide 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?

The tool has no parameters, so the description correctly omits any parameter details. There is nothing more to explain.

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 explicitly lists all relevant query intents: who is on the team, seats, roles, pending invitations, and team-member actions. It clearly distinguishes itself as a listing/read operation among the many sibling tools.

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

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

It states 'Use this when the user asks...' providing clear when-to-use guidance. It does not explicitly mention when not to use it or point to alternatives for modifications, but the read-only context is implicit.

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 it as read-only and non-destructive. The description adds the detail that it returns event keys and labels, which gives a bit more insight into the output, though it doesn't deeply elaborate on formatting or side effects. Overall, it is transparent enough.

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 concise, only two sentences, with no unnecessary wording. It efficiently conveys purpose, usage, and key behavioral aspects.

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 listing tool with no parameters and no declared output schema, the description provides enough context: what it returns, when to use it, and that it is read-only. No crucial information appears to be 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 no parameters, so the schema is fully covered. The description does not need to explain parameters but the baseline for zero parameters is 4, and it does not contradict or confuse.

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?

Clearly states the tool lists webhook events, event names, or callback triggers, and specifies it returns supported event keys and labels. This distinguishes it from sibling tools like list-webhook-subscriptions and list-webhook-logs.

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

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

Explicitly notes when to use it: when the user asks what webhook events are available before creating or editing a subscription. Also indicates it is read-only, reinforcing that it does not modify subscriptions, which guides 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 mark it read-only and non-destructive. The description adds that results are bounded and scoped to owned subscriptions, which is useful behavioral context beyond the schema.

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, front-loaded with the primary use case, and no filler. Every sentence adds either usage context or a routing instruction.

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

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

For a read-only list tool with four optional parameters and no output schema, the description covers purpose, scope, boundedness, and a prerequisite routing step. It doesn't enumerate return fields, but 'delivery log summaries' plus the schema is adequate 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?

Schema description coverage is 100%, so the schema fully documents all four optional parameters. The description adds no parameter-level detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description opens with a specific use case ('whether webhooks delivered, failed, retried, or what payload event logs exist') and names the resource ('delivery log summaries for owned subscriptions'). It clearly identifies this as a read-only listing tool, distinct from subscription management 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?

Explicitly states the triggering user request and directs the agent to call list-webhook-subscriptions first when a subscription ID is needed. This gives clear when-to-use and a concrete routing rule, though it doesn't contrast with list-webhook-events.

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 explicitly states 'Read-only: returns owned webhook subscriptions without changing them,' which aligns perfectly with the readOnlyHint annotation. No contradiction exists, and the 'owned' scope adds clarity beyond the annotation.

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

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

The description is two sentences, tightly packed with purpose, usage trigger, and read-only nature. No fluff or redundant phrasing.

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 empty parameter schema and no output schema, the description fully covers what the tool does, when to use it, and points to a related tool for event discovery. Nothing essential is missing.

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

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

The schema has no parameters, so coverage is effectively 100%. Per the baseline rule, a score of 3 is appropriate since the description adds no parameter-specific information (none needed).

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 ('list') and resource ('webhook subscriptions'), and clearly defines the trigger ('when the user asks which webhooks... are configured'). It implicitly differentiates from other list tools by focusing on webhook subscriptions, and explicitly references list-webhook-events for event keys.

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 provides explicit 'when to use' guidance ('Use this when the user asks...') and names an alternative (list-webhook-events) for discovering valid event keys, giving the agent clear direction on 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds real value beyond them: it discloses that the operation is state-changing, requires prior authorization, and can alter content visibility in a public Space.

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, front-loaded with the action triggers and followed by the state-change caveat and parameter requirements. Efficient, though the opening sentence packs several verbs together and could be marginally tighter.

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

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

For a state-changing mutation with annotations and a fully documented schema, the description covers purpose, side effects, authorization, and parameter sourcing. Return behavior is unspecified but no output schema exists; the remaining gap is minor.

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

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

Schema coverage is 100%, so the schema documents all four params (baseline 3). The description adds meaning by reinforcing which IDs are required and by telling the agent where parent_id and order values should come from (list-space-documents), which the schema does not.

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 specific verbs (move, nest, unnest, reorder, reposition) and the resource types affected (page/document, folder, external link). This clearly distinguishes it from update-space-item (content edits) and copy-space-item (duplication) among the 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?

Explicitly frames the trigger ('Use this when the user wants to move, nest, unnest, reorder, or reposition...') and points to list-space-documents as the source for parent_id/order values. It does not, however, name a sibling alternative or a when-not-to-use condition.

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

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

Beyond the annotations (destructiveHint: true, readOnlyHint: false), the description explicitly labels it a 'destructive action' and mentions 'After authorization', providing additional context about the tool's side effects and prerequisite. It also discloses limitations on who can be removed, which is valuable behavioral information.

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 concise, consisting of two sentences with no redundant information. It front-loads the primary action and includes necessary constraints and authorization context without unnecessary elaboration.

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 tool with a single parameter and no output schema, the description is complete. It covers the action, the effect (revoking access), the constraint (owners/acting user), and the authorization requirement. No additional context is needed for an agent to use 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 member_id parameter description adds meaningful context beyond the schema: it clarifies the parameter is a numeric ID, specifies it refers to a user/member, and advises using list-team-members first when the user provides a name or email. This directly helps the agent correctly populate the parameter.

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

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

The description clearly states the tool's purpose: to remove an existing teammate and revoke their access to team Spaces. It uses specific verbs ('remove', 'revoke') and the resource ('teammate', 'team Spaces'), distinguishing it from sibling tools like invite-team-member or update-team-member-role.

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 'Use this when the user explicitly wants to remove an existing teammate', providing direct guidance on when to select this tool. It also notes constraints (owners and acting user cannot be removed) and the parameter description advises using list-team-members first when given a name/email, offering clear alternative paths.

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 only declare readOnlyHint=false, openWorldHint=true, destructiveHint=true; the description adds substantial context beyond them, notably that this is state-changing, requires authorization, and that submission failures may forward a feedback preview plus account context to an external error-monitoring service. That is a real privacy/data-flow disclosure an agent would not otherwise know. It stops short of explaining the destructiveHint flag or what the caller sees on success.

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

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

Three sentences, each carrying distinct payload: trigger condition, behavior/data flow, and content rule. The trigger is front-loaded. Minor cost: the middle sentence is dense and shifts subject mid-clause ('After authorization, this state-changing action...'), which slightly slows parsing.

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 one-parameter tool with no output schema, the description supplies trigger, mutation semantics, authorization, failure-path data handling, and content guidance. Only the success/confirmation behavior and the reasoning behind destructiveHint are unstated, which are minor omissions at this 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 coverage is 100% and the single parameter is documented in-schema, including the 10-character minimum, so the baseline is 3. The description adds genuine value on top with the content restriction about secrets and source code, which is guidance the schema does not carry.

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 and resource ('records feedback for review') and frames the scenario in which it fires (user explicitly asks to submit DocuWriter.ai or MCP feedback). It is unambiguous and clearly distinct from every sibling, none of which submit feedback. The 'what' is slightly subordinated to the trigger sentence, which keeps it just short of ideal front-loading.

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

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

Gives an explicit usage condition: only when the user explicitly asks to submit feedback, which is a meaningful restriction since the agent must not volunteer this action. It also adds a content rule ('Do not include secrets or source code in feedback'). No named alternative exists among the siblings, so there is nothing further to route against.

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