Generate, search, and manage codebase documentation on DocuWriter.ai. 72 tools incl. Autopilot.
Scored across 72 tools
Each tool has a highly specific name and detailed description that clearly distinguishes it from others, even in areas with many similar actions (e.g., generation types, space item operations, webhook management). No two tools appear to overlap in purpose.
All 72 tool names follow a consistent lowercase-with-hyphens verb-noun pattern (e.g., list-spaces, generate-code-documentation, update-webhook-subscription). The naming convention is uniform and predictable across the entire set.
Though 72 tools is far above the typical 3-15 range, the server covers a sprawling domain (Space management, code generation, repository links, suggestions, webhooks, team administration, provider connections, AI preferences, etc.), and each tool addresses a distinct, necessary operation with no redundancy. The count is justified by the product's scope.
The tool surface provides comprehensive CRUD and action coverage for all major features of DocuWriter.ai: Spaces (including documents, items, suggestions, repository links, activity, export), generators (multiple types, versioning, restore), providers, webhooks, team, AI preferences, user info, search, and feedback. No critical operations appear missing.
Use this when the user wants to save, publish, or add an existing generated output/result into a documentation Space. State-changing: creates a generation-backed Space item after authorization. Requires generation_id, destination space_id, and optional parent_id/title.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional custom Space item title. Defaults to the generation filename. | |
| space_id | Yes | Target numeric Space ID. Call list-spaces first. | |
| parent_id | No | Optional parent folder ID in the target Space. | |
| generation_id | Yes | Generation ID to add to a Space. Call list-generations first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only and not destructive, but the description adds valuable context: it explicitly calls out 'State-changing: creates a generation-backed Space item' and notes that authorization is required. This goes beyond the annotations by explaining the operation's nature and prerequisite.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with usage guidance and state-changing behavior. No redundant content; 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 description covers when to use, state-changing nature, authorization, and required parameters. It does not mention the return value or error conditions, but for a mutation tool without an output schema, it provides sufficient context for correct invocation. The omission is minor given 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?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal semantic value beyond restating required/optional parameters and using 'destination' for space_id, which is a slight clarification. This meets the baseline of 3 for high 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: saving, publishing, or adding an existing generated output to a documentation Space. It distinguishes from generation tools by emphasizing 'existing generated output/result', making it distinct from siblings like 'generate-and-add-documentation'.
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 to save, publish, or add an existing generated output') and implies the prerequisite that the generation must already exist. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over generation-focused tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to apply or accept one pending Autopilot/repository-sync documentation suggestion. Destructive state-changing action: writes the suggested content to the target Space document and marks the suggestion applied after authorization. Requires suggestion_id from list-space-suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| suggestion_id | Yes | The numeric ID of the RepositoryDocSuggestion to apply. |
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.
Use this when the user wants to archive, hide, or remove an existing generation from the active generation list without deleting it. State-changing: archives the visible generation after authorization. Requires generation_id from list-generations.
| Name | Required | Description | Default |
|---|---|---|---|
| generation_id | Yes | Generation ID to archive. Call list-generations first. |
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.
Use this when the user wants to apply or discard multiple Autopilot/repository-sync suggestions at once. Destructive state-changing action: bulk apply can update multiple Space documents, and bulk discard removes suggestions from active review after authorization. Requires suggestion IDs from list-space-suggestions; bulk apply requires Enterprise access.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Numeric Autopilot suggestion IDs to bulk apply or discard. | |
| action | Yes | Bulk suggestion action to perform: apply or discard. |
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.
Use this when the user wants to cancel a pending team invitation before it is accepted. After authorization, this destructive action removes the specified invitation_id so that invitation can no longer be accepted.
| Name | Required | Description | Default |
|---|---|---|---|
| invitation_id | Yes | Numeric pending team invitation ID to cancel. Use list-team-members first when the user gives an invitee email. |
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.
Use this when the user wants to copy, duplicate, or clone a Space page/document, folder, or external link and its children into another Space. State-changing: creates copied items in the target Space after authorization. Requires source_space_id, item_id, target_space_id, and optional target_parent_id.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Source Space item ID. | |
| source_space_id | Yes | Numeric source Space ID that currently contains the item to copy. | |
| target_space_id | Yes | Numeric destination Space ID where the copied item should be created. | |
| target_parent_id | No | Optional target parent folder ID, or null for root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Clearly discloses that this is state-changing, creates copies in the target Space, and includes children. This adds context beyond the annotation values and does not contradict readOnlyHint=false or destructiveHint=false.
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?
Front-loaded with a clear usage trigger and kept to two sentences, but the 'Requires...' sentence duplicates schema information and the synonym chain 'copy, duplicate, clone' is slightly redundant.
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 what is copied, that children are included, where the copy is created, and the side effect. Missing details like naming conflicts or permission requirements are not critical 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 coverage is 100% and each parameter is already described in the input schema. The free-text description does not add meaningful per-parameter semantics beyond repeating the 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?
Names the exact operation (copy/duplicate/clone), the resource types (Space page/document, folder, external link), and the destination (another Space), which distinguishes it from siblings like move-space-item and create-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?
Explicitly says 'Use this when the user wants to copy...' and lists required parameters, but it does not explicitly mention alternatives such as move-space-item or create-space-item for non-copy actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks how many Autopilot/repository-sync suggestions are pending, snoozed, done, high-confidence, or waiting for review. Read-only: returns grouped counts without changing suggestions or documents. Optionally filter by numeric space_id.
| Name | Required | Description | Default |
|---|---|---|---|
| space_id | No | Optional Space filter. |
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.
Use this when the user wants to create a new documentation Space or knowledge base container. State-changing: creates the Space directly after the MCP client authorizes the call. Requires a Space name and may include description, public visibility, and slug.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the new documentation Space the user wants to create. | |
| slug | No | Optional public slug. | |
| is_public | No | Whether the Space should be public. Defaults to false. | |
| description | No | Optional Space description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it is state-changing and occurs after MCP client authorization, adding context beyond the annotations (readOnlyHint=false, destructiveHint=false). It does not detail all side effects, but enough is provided for a create 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?
The description is two sentences, directly stating purpose and key requirements. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation, the description covers the essential trigger, required field, and state-changing nature. It does not mention output or side effects, but these are not necessary given the tool's simplicity and 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?
All four parameters have schema descriptions, and the tool description summarizes them (name required, plus slug, is_public, description). This adds minimal value beyond the schema, as it only restates what is already explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new documentation Space or knowledge base container, with a specific verb and resource. It distinguishes from sibling tools like create-space-document and create-space-item by focusing on the space itself.
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 create a new documentation Space', providing a clear trigger condition. It does not mention alternatives or when-not-to-use, but the context is straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to create a markdown document/page in a Space from provided content. State-changing: creates the document directly after authorization. Requires numeric space_id, title, and markdown content. Use create-space-item for folders or external links.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Folder path for the document (e.g., "docs/api") - creates folders if they don't exist | |
| title | Yes | The title of the document | |
| content | Yes | The content of the document in markdown format | |
| space_id | Yes | The numeric ID of the space to create the document in. Call list-spaces first. | |
| parent_id | No | The numeric ID of the parent folder (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description openly states that the tool is state-changing and creates the document directly after authorization. This aligns with the annotations (readOnlyHint false, destructiveHint false) and adds useful context about the direct creation behavior 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 and well-structured, using only a few sentences to convey purpose, timing, requirements, and the distinction from a sibling tool. No redundant or extraneous information is included.
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 input schema and the presence of clear annotations, the description provides sufficient context for an agent to decide when and how to use the tool. It covers the main use case, required inputs, and the relevant alternative tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description highlights the required parameters and notes that space_id is numeric, but does not elaborate on the optional path or parent_id beyond what the schema already provides. Since the schema has 100% coverage with clear descriptions, the added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a markdown document/page in a Space from provided content, and explicitly distinguishes it from create-space-item, which is for folders or external links. This makes the tool's purpose specific 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?
It explains when to use the tool (user wants to create a markdown document) and what is required (numeric space_id, title, markdown content). It also explicitly points to create-space-item as the alternative for folders or external links, providing clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to create a Space page/document, folder, or external link inside an existing Space. State-changing: creates the item directly after authorization. Requires numeric space_id, item type, title, and content or URL when relevant.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional folder path to create/use. | |
| type | Yes | page, folder, or external_link. | |
| title | Yes | Title for the new Space page/document, folder, or external link. | |
| content | No | Markdown content for page items. | |
| space_id | Yes | Numeric Space ID where the page, folder, or external link should be created. | |
| parent_id | No | Optional numeric parent folder item ID, or null to create at the Space root. | |
| external_url | No | URL for external_link items. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it is state-changing and creates an item 'directly after authorization', which aligns with annotations (readOnlyHint=false). It adds minor context about authorization but does not disclose side effects, permissions, or failure behaviors beyond what annotations imply.
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, compact sentence that clearly conveys the tool's core purpose and key conditions without redundancy or 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?
Given the tool's moderate complexity and absence of an output schema, the description covers the essential context: what it creates, where, and the type-based content requirements. It lacks details on expected return values or edge cases, but these are not required given the schema and no output specification.
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 7 parameters have schema descriptions, so coverage is 100%. The description adds a small hint that 'content or URL' is relevant depending on type, but this largely reiterates schema details. No significant additional meaning is provided 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?
States a specific verb ('create') and resource ('Space item') with explicit item types (page/document, folder, external_link). However, it does not explicitly distinguish from the sibling 'create-space-document' tool, which may overlap with the page/document type.
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 'Use this when...' condition, but does not mention when not to use it or direct users to an alternative tool (e.g., create-space-document for documents). This leaves some ambiguity in tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to link an authorized provider repository to a Space for Autopilot sync. After authorization, this state-changing external action creates the link with triggers, path filters, notifications, or auto-apply settings and requires Enterprise access.
| Name | Required | Description | Default |
|---|---|---|---|
| branch | Yes | Repository branch name that Autopilot should monitor for this link. | |
| provider | Yes | github, gitlab, bitbucket, or azure. | |
| space_id | Yes | Numeric Space ID where the Autopilot repository link should be created. | |
| path_filters | No | Optional path filters. | |
| trigger_events | Yes | push and/or pr_merge. | |
| auto_apply_enabled | Yes | Enterprise auto-apply flag. | |
| repository_identifier | Yes | Provider repository identifier. | |
| ai_context_instructions | No | Optional AI instructions. | |
| auto_apply_threshold_pct | Yes | Auto-apply threshold percent from 95 to 100. | |
| notify_on_new_suggestions | Yes | Email notification flag. | |
| notification_channels_input | Yes | Notification channel settings. |
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.
Use this when the user wants to add a webhook, callback URL, n8n/Zapier endpoint, or integration subscription for supported DocuWriter events. State-changing external action: creates the subscription after authorization. Use list-webhook-events first for valid event keys; webhook test dispatch is not exposed.
| Name | Required | Description | Default |
|---|---|---|---|
| events | Yes | Event keys from list-webhook-events. | |
| metadata | No | Optional metadata object to store alongside the webhook subscription. | |
| webhook_url | Yes | HTTP/HTTPS webhook endpoint. |
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.
Use this when the user explicitly wants to delete a whole documentation Space. Destructive state-changing action: removes the manageable Space directly after the MCP client authorizes the call. Requires numeric space_id from list-spaces and should not be used for deleting individual pages.
| Name | Required | Description | Default |
|---|---|---|---|
| space_id | Yes | Numeric Space ID to delete. Use list-spaces first and confirm the user means the whole Space. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly labels the action as 'destructive state-changing' and says it 'removes' the Space, aligning with the annotations (destructiveHint: true, readOnlyHint: false). It adds a note about MCP client authorization, which slightly exceeds the annotations but does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, but includes some redundant phrasing like 'manageable' and 'directly after the MCP client authorizes.' It is still concise and front-loaded with the primary purpose, so it loses only a point for minor wordiness.
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 delete operation with one parameter and no output schema, the description covers the purpose, usage condition, parameter source, and an explicit exclusion (not for individual pages). It is complete enough for an agent to invoke correctly without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description mentions that a numeric space_id is required and that it should come from list-spaces, complementing the schema's parameter description which already provides detailed context. The schema coverage is 100% for the single parameter, and the description adds extra sourcing guidance.
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 delete a whole documentation Space. It uses a specific verb ('delete') and resource ('Space'), and explicitly distinguishes this from deleting individual pages, making its scope 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 provides clear when-to-use guidance: only when the user explicitly wants to delete an entire Space. It also instructs to use list-spaces first and confirms the user's intent, and explicitly warns against using it for individual pages, which effectively differentiates it from related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user explicitly wants to delete one existing Space document/page. Destructive state-changing action: deletes the document directly after authorization. Requires the document ID from list-space-documents or search results; use delete-space-items for folders or bulk item deletion.
| Name | Required | Description | Default |
|---|---|---|---|
| space_id | Yes | The numeric ID of the space containing the document. Call list-spaces first. | |
| document_id | Yes | The numeric ID of the document to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that this is a destructive, state-changing action that deletes the document directly after authorization. While destructiveHint=true already signals danger, the description adds meaningful context about direct deletion and the need for an explicit ID from a prior lookup.
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 wasted words: when to use, what happens, and where the required ID comes from. The most critical warning ('destructive') is front-loaded, and every sentence contributes actionable 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?
With only two well-documented parameters, destructiveHint=true annotations, a clear usage trigger, and a named alternative for nearby cases, nothing essential is missing. The description fully equips an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented. The description adds extra value by explaining where document_id must come from (list-space-documents or search results), which is provenance information beyond the schema's type and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('delete'), a precise resource ('one existing Space document/page'), and immediately distinguishes itself from delete-space-items for folders or bulk deletion. An agent can clearly tell what this tool does and how it differs from its closest sibling.
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 exactly when to use it ('when the user explicitly wants to delete one existing Space document/page'), specifies the required ID source (list-space-documents or search results), and explicitly routes folder/bulk deletion to delete-space-items. This gives clear selection guidance with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to delete one or more Space pages, documents, folders, or external links from a Space. Destructive state-changing action: deletes the selected items directly after the MCP client authorizes the call. Requires numeric space_id and item_ids from list-space-documents.
| Name | Required | Description | Default |
|---|---|---|---|
| item_ids | Yes | Space item IDs to delete. | |
| space_id | Yes | Numeric Space ID containing the items that should be deleted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey destructiveHint=true and readOnlyHint=false. The description adds that it is a 'destructive state-changing action' and that deletion happens 'directly after the MCP client authorizes the call,' which gives a small behavioral nuance beyond the annotations (immediate effect). However, it does not elaborate on irreversibility or additional side effects, so it only marginally extends the annotation-provided 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 two sentences with zero redundancy. It front-loads the usage condition, then states the destructive nature and prerequisite compactly. Every sentence carries useful information without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with only 2 parameters, no output schema, and annotations covering safety, the description provides the essential context: the use case, the destructive consequence, and the source of IDs. It does not cover return values or error cases, but these are likely unnecessary for this operation. The coverage is adequate for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters fully (100% coverage). The description adds value by specifying that item_ids should be obtained from list-space-documents, clarifying the source of valid IDs and reinforcing that space_id must be numeric. This goes beyond the schema's basic descriptions and helps an agent know how to populate the parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('delete') and resource ('Space pages, documents, folders, or external links from a Space'), and differentiates it from sibling tools like delete-space-document (single document) and delete-space (whole space) by limiting scope to items within a Space. The listing of item types adds precision.
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...' condition tied to user intent and notes a prerequisite that IDs come from list-space-documents. However, it does not mention when NOT to use this tool or point to alternatives (e.g., delete-space-document or delete-space), so the guidance is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to remove an Autopilot repository link from a Space. Destructive external-provider action: deletes the link after authorization and may remove provider webhook configuration. Requires Enterprise access, manageable Space permission, space_id, and link_id.
| Name | Required | Description | Default |
|---|---|---|---|
| link_id | Yes | Numeric repository link ID to delete. Use list-space-repository-links first when needed. | |
| space_id | Yes | Numeric Space ID containing the Autopilot repository link to delete. |
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.
Use this when the user wants to remove a webhook subscription or stop sending events to an endpoint. Destructive external action: deletes the owned subscription after authorization. Requires subscription_id from list-webhook-subscriptions; webhook test dispatch is not exposed.
| Name | Required | Description | Default |
|---|---|---|---|
| subscription_id | Yes | Webhook subscription ID. |
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.
Use this when the user wants to pause, turn off, or disable an Autopilot repository link for a Space. State-changing external-provider action: disables the link and attempts to remove the provider webhook after authorization. Requires Enterprise access, manageable Space permission, space_id, and link_id.
| Name | Required | Description | Default |
|---|---|---|---|
| link_id | Yes | Numeric repository link ID to disable. Use list-space-repository-links first when needed. | |
| space_id | Yes | Numeric Space ID containing the Autopilot repository link to disable. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing that this is a state-changing external-provider action, that it attempts to remove the provider webhook, and that authorization is required. This provides important behavioral context not captured by readOnlyHint or destructiveHint.
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. It front-loads the trigger condition, then provides side-effect and permission context in a compact paragraph. No unnecessary information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description provides all necessary context: when to use it, what it does, side effects, and required permissions. Sibling tools are not referenced, but the description is self-sufficient 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?
Both parameters are fully described in the schema. The link_id description adds practical guidance by recommending list-space-repository-links first when needed, which exceeds the baseline. The space_id description is straightforward but sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: disabling an Autopilot repository link for a Space. It uses a specific verb ('disable'), identifies the resource ('repository link'), and distinguishes the action from related operations like enabling or updating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool ('when the user wants to pause, turn off, or disable'), giving a clear trigger condition. It doesn't explicitly mention alternatives or exclusions, but the trigger is clear enough for an agent to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to reject, dismiss, remove from review, or discard one Autopilot/repository-sync documentation suggestion. Destructive state-changing action: marks the pending suggestion discarded directly after authorization. Requires suggestion_id from list-space-suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| suggestion_id | Yes | Numeric Autopilot suggestion ID to discard. Use list-space-suggestions first when needed. |
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.
Use this when the user wants to turn on or resume an existing Autopilot repository sync link for a Space. State-changing external-provider action: enables the link and registers the provider webhook after authorization. Requires Enterprise access, manageable Space permission, provider access, space_id, and link_id.
| Name | Required | Description | Default |
|---|---|---|---|
| link_id | Yes | Numeric repository link ID to enable. Use list-space-repository-links first when needed. | |
| space_id | Yes | Numeric Space ID containing the Autopilot repository link to enable. |
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.
Use this when the user wants a Markdown export of selected Space pages, folders, or docs that can be returned in the MCP response. Read-only: returns merged Markdown without changing Space content. Use browser guidance for PDF, ZIP, or download-only export flows.
| Name | Required | Description | Default |
|---|---|---|---|
| item_ids | Yes | Space item IDs to export. | |
| space_id | Yes | Numeric Space ID containing the selected items to export as Markdown. |
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.
Use this when the user supplies source files and wants the generated documentation saved directly in an existing Space. After authorization, this state-changing action consumes AI credits, creates a generation, and writes a document to the specified space_id.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional custom name used to identify the documentation in generation history | |
| path | No | Folder path for the document (e.g., "docs/api") - creates folders if they don't exist | |
| files | Yes | Array of files to document. Each file must have filename and source_code properties | |
| title | Yes | Title for the document in the space | |
| space_id | Yes | The numeric ID of the space to add the documentation to. Call list-spaces first. | |
| parent_id | No | The numeric ID of the parent folder (optional) | |
| output_language | No | Output language for documentation | |
| documentation_type | No | Free-text style hint for this single document, e.g. 'API Reference', 'Tutorial', 'General Documentation' (the default). This is NOT a Space's full-tree documentation audience — any string is accepted and passed to the prompt as-is. | |
| additional_instructions | No | Additional instructions for documentation generation |
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.
Use this when the user wants a new documentation Space built from selected files in an imported repository. After authorization, this state-changing action consumes AI credits, creates a private Space, links the repository, and queues per-file jobs using repository_id and selected_files.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Optional human language for the generated per-file codebase documentation. Defaults to English. | |
| space_name | No | Optional name for the new documentation Space. If omitted, the platform creates a generated name from repository, branch, and timestamp. | |
| repository_id | Yes | Required numeric ID of an already connected/imported repository from the user repository records; do not pass a slug, URL, provider name, or Space repository-link ID. | |
| selected_files | Yes | Required repository file paths already selected from the imported repository tree, such as app/Models/User.php or routes/api.php. This tool creates one Space with per-file queued docs; use browser guidance if the user still needs to choose files. | |
| additional_instructions | No | Optional customer instructions for documentation tone, scope, examples, framework focus, or project-specific emphasis applied to every queued file. |
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.
Use this when the user supplies source code and asks to add inline comments, docblocks, docstrings, or code annotations. State-changing generation action: consumes AI credits, creates a generation, and returns commented code after authorization. Use browser guidance for file uploads.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional custom name used to identify the commented code in generation history | |
| filename | Yes | The full file path of the file being commented (e.g., src/utils/helper.ts) | |
| source_code | Yes | The source code to add comments to |
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.
Use this when the user supplies source code and asks to generate markdown documentation, explain code, or document one or more files. State-changing generation action: consumes AI credits, creates a generation, and returns documentation after authorization. Use browser guidance for local upload or repository/full-tree flows.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional custom name used to identify the documentation in generation history | |
| files | Yes | Array of files to document. Each file must have filename and source_code properties | |
| output_language | No | Output language for documentation | |
| documentation_type | No | Free-text style hint for this single document, e.g. 'API Reference', 'Tutorial', 'General Documentation' (the default). This is NOT a Space's full-tree documentation audience — any string is accepted and passed to the prompt as-is. | |
| additional_instructions | No | Additional instructions for documentation generation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, etc.), the description discloses that this is a 'State-changing generation action' that 'consumes AI credits, creates a generation, and returns documentation after authorization.' This adds valuable side-effect and authorization context that annotations do not provide, though it does not describe return format 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 sentences, both essential. The purpose is front-loaded in the first sentence, and the second sentence adds critical side-effect and routing context. No filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters, all documented in the schema, and no output schema, the description adequately covers when to use it, side effects, and routing guidance. It does not explain the return structure, but that is less critical given the schema and the fact that the description mentions 'returns documentation'.
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 parameters. The description adds nuance to 'documentation_type' by clarifying it is a free-text style hint and NOT a Space's full-tree documentation audience, which helps avoid misinterpretation. It does not add detail to other parameters but the added clarification lifts it above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('generate'), resource ('markdown documentation'), and the exact trigger condition ('user supplies source code and asks to generate markdown documentation, explain code, or document one or more files'). It also differentiates from siblings by specifying it handles one or more files, not full-tree or repository 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 tells when to use it ('when the user supplies source code and asks to generate markdown documentation, explain code, or document one or more files') and points to browser guidance for local upload or repository/full-tree flows, which indirectly steers away from siblings like generate-repository-documentation. However, it does not explicitly name alternatives or state when not to use this tool, leaving some inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user supplies source code and asks for an optimized or refactored version. After authorization, this state-changing action consumes AI credits, creates a generation, and returns the revised code.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional custom name used to identify the optimized code in generation history | |
| filename | Yes | The full file path of the file being optimized (e.g., src/utils/helper.ts) | |
| source_code | Yes | The source code to optimize | |
| optimization_focus | No | Focus area for optimization (default: Performance) | |
| additional_instructions | No | Additional instructions for code optimization |
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.
Use this when the user supplies source code and asks to generate unit, feature, integration, or framework-specific tests. State-changing generation action: consumes AI credits, creates a generation, and returns test code after authorization. Use browser guidance for local uploads or repository-wide test generation.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional custom name used to identify the tests in generation history | |
| filename | Yes | The full file path of the file being tested (e.g., src/utils/helper.ts) | |
| test_type | No | Type of tests to generate (e.g., "unit tests", "integration tests") | |
| source_code | Yes | The source code to generate tests for | |
| test_framework | No | Testing framework to use (e.g., "Jest", "PHPUnit", "JUnit") or "auto-detect" | |
| additional_instructions | No | Additional instructions for test generation |
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.
Use this when the user has reviewed a full-tree preview and asks to create its documentation Space. After authorization, this state-changing action consumes AI credits, creates a private linked Space, and queues documentation from the stored preview using repository_id and accepted_tree_hash.
| Name | Required | Description | Default |
|---|---|---|---|
| space_name | No | Optional name for the new full-tree documentation Space. If omitted, the repository name is used. | |
| repository_id | Yes | Required numeric ID of the imported repository that already has a generated full-tree documentation preview. Do not pass a Space ID, repository slug, provider URL, or Autopilot repository-link ID. | |
| excluded_paths | No | Optional metadata listing known repository paths the user intentionally excluded during tree review. This is reported back for clarity and does not perform file deletion. | |
| accepted_tree_hash | Yes | Required SHA-256 tree_hash returned by get-full-tree-documentation-preview. Include it only after the user approved that exact stored preview; if it no longer matches, refresh preview before submitting. Do not send documentation_tree. |
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.
Use this when the user supplies one source-code file and asks to convert it to another programming language or framework. After authorization, this state-changing action consumes AI credits, creates a generation, and returns converted code using source_code, filename, from_language, and to_language.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional generation history name for the converted output. Defaults to the supplied filename when omitted. | |
| filename | Yes | Filename for the supplied source code, including extension when known, so the generator can name the generation and understand context. | |
| source_code | Yes | Source code contents to convert. Use this only when the customer supplied the code text to the MCP client; use browser guidance for local file picker uploads. | |
| to_language | Yes | Target programming language or framework to convert to, such as TypeScript, Python, Go, Vue, TailwindCSS, CSS, or Laravel. | |
| from_language | Yes | Source programming language or framework to convert from, such as PHP, JavaScript, Python, React, Bootstrap, CSS, or Laravel. | |
| save_to_space | No | Optional destination Space item for saving the converted code after authorization. The authenticated user must be able to manage that Space. | |
| additional_instructions | No | Optional conversion guidance, such as preserving APIs, using a framework version, matching style conventions, or focusing on compatibility. |
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 returns converted code. It could be more explicit about save_to_space behavior, but the parameter description covers that. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and reasonably concise, but it redundantly lists parameter names at the end ('using source_code, filename, from_language, and to_language') which does not add much 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?
Given there is no output schema, the description adequately states that the tool returns converted code and mentions key side effects like credit consumption and generation creation. It does not detail response structure, but that is not critical for invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All seven parameters have schema descriptions, and the tool description reinforces some by naming key parameters. The parameter descriptions provide useful examples and usage conditions, though 'name' and 'source_code' could be slightly clearer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific use case: converting a user-supplied source-code file to another programming language or framework. This distinguishes it from sibling tools that generate documentation, comments, tests, or other code artifacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use the tool ('when the user supplies one source-code file and asks to convert it'). This is sufficient to route the agent correctly among many similar code-generation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants one markdown document generated from selected files in an imported repository. After authorization, this state-changing action consumes AI credits and creates a generation using numeric repository_id and selected_files, with optional Space saving.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | No | Optional generation history filename. Defaults to the selected repository documentation naming pattern. | |
| language | No | Optional human language for the generated repository documentation. Defaults to English. | |
| repository_id | Yes | Required numeric ID of an already connected/imported repository from the user repository records; do not pass a slug, URL, provider name, or Space repository-link ID. | |
| save_to_space | No | Optional destination Space page to create from the generated documentation after authorization. The authenticated user must manage the Space. | |
| selected_files | Yes | Required repository file paths already selected from the imported repository tree, such as app/Models/User.php or routes/api.php. Use browser guidance if the user still needs to choose files. | |
| additional_instructions | No | Optional customer instructions for documentation tone, scope, examples, framework focus, or project-specific emphasis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the action is state-changing, consumes AI credits, and requires authorization, which goes beyond the annotations (readOnlyHint=false, destructiveHint=false). It does not detail all side effects, but the key behavioral aspects are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose and followed by behavioral notes. It is concise, clear, and every sentence contributes meaning without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, nested object, no output schema), the description covers the main action, side effects, and authorization requirement. It does not expand on the nested save_to_space object, but the schema description handles that, so the description 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 description reiterates that repository_id and selected_files are used and that Space saving is optional, but these details are already present in the schema with 100% coverage. No additional parameter insight is provided, 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 that the tool generates one markdown document from selected files in an imported repository. It does not explicitly name sibling tools, but the phrase 'selected files' implicitly differentiates it from whole-tree 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?
It provides a usage condition ('when the user wants one markdown document generated from selected files'), but does not mention any alternative tools or describe when not to use this tool. The lack of explicit sibling comparison leaves the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks to generate or refresh a README for an imported repository. After authorization, this state-changing action consumes AI credits, creates a generation, and can save it to a Space; it requires the numeric repository_id.
| Name | Required | Description | Default |
|---|---|---|---|
| license | No | Optional license value for the README; required when sections includes License. | |
| filename | No | Optional generation history filename. Defaults to README.md plus the repository name. | |
| language | No | Optional human language for the generated README. Defaults to English. | |
| sections | No | Optional README sections to include, such as Introduction, Features, Requirements, Installation, Usage, Configuration, Contributing, or License. | |
| repository_id | Yes | Required numeric ID of an already connected/imported repository from the user repository records; do not pass a slug, URL, provider name, or Space repository-link ID. | |
| save_to_space | No | Optional destination Space page to create from the generated README after authorization. The authenticated user must manage the Space. | |
| additional_instructions | No | Optional customer instructions for README tone, scope, installation focus, examples, or project-specific emphasis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly says the action is state-changing, creates a generation, consumes AI credits, and may save to a Space, which complements the readOnlyHint=false annotation. It does not mention rate limits, but that is not critical for this tool; the main side effects are disclosed.
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 fairly compact and front-loaded with the main purpose, then covers side effects and key parameter constraints. A few phrases such as 'After authorization, this state-changing action' are slightly redundant with the annotations, but overall it is well-structured and not verbose.
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 for the intended behavior and important constraints, including authorization, credit consumption, and the optional Space destination. Since there is no output schema, it does not need to explain return values, but it could have noted what the caller should expect back (e.g., a generation object) for fuller completeness.
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?
Every parameter in the schema is described, and the description adds crucial guidance beyond the schema: repository_id must be a numeric ID and not a slug/URL/provider name/Space link, save_to_space requires the user to manage the Space, and sections are given example values. This significantly clarifies correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (generate or refresh a README) and the resource (an imported repository), and explicitly notes it consumes AI credits and can save to a Space. This distinguishes it from sibling tools like generate-repository-documentation or generate-codebase-documentation.
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 a clear 'use this when' trigger and mentions the authorization requirement, but does not explicitly contrast with sibling generation tools. The phrase 'imported repository' helps scope usage, though a direct 'use X instead for Y' would be stronger.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants release notes from two branches of a connected provider repository. After authorization, this state-changing action compares base_branch with compare_branch, consumes AI credits, creates a generation, and can save it to a Space.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | No | Optional generation history filename. Defaults to release notes plus the repository name and base branch. | |
| provider | Yes | Required connected Git provider key or display name: github, gitlab, bitbucket, azure, or Azure DevOps. Provider authorization must already be complete. | |
| base_branch | Yes | Required base branch to compare from, such as main or production. Must be different from compare_branch. | |
| save_to_space | No | Optional destination Space page to create from the generated release notes after authorization. The authenticated user must manage the Space. | |
| compare_branch | Yes | Required compare branch to compare into the base branch, such as develop, release/1.2, or feature branch name. | |
| repository_identifier | Yes | Required provider repository identifier such as owner/repo for GitHub, GitLab, or Bitbucket, or organization/project/repository for Azure DevOps. | |
| additional_instructions | No | Optional customer instructions for release note tone, audience, format, breaking-change emphasis, or product area focus. |
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.
Use this when the user supplies API source code and asks for an OpenAPI or Swagger specification. After authorization, this state-changing action consumes AI credits, creates a generation, and returns OpenAPI JSON; it accepts one source_code file or multiple files entries.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional generation history name for the generated OpenAPI output. Defaults to the supplied filename or comma-separated filenames. | |
| files | No | Multiple supplied file contents for one OpenAPI spec. Use this when the customer pasted or supplied several files directly; use browser guidance for local uploads. | |
| filename | No | Filename for source_code in the single-file path. Omit when using files[]. | |
| source_code | No | Source code to analyze for a single supplied file. Provide filename too. Omit when using files[]. | |
| save_to_space | No | Optional destination Space item. | |
| additional_instructions | No | Optional generation instructions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it is a state-changing action, consumes AI credits, creates a generation, and returns OpenAPI JSON—information not present in the annotations (which only indicate non-read-only and non-destructive).
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-load the purpose and then cover core behavior and input modes. No redundancy or extraneous 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?
While the schema covers all parameters (including optional save_to_space and additional_instructions), the description does not mention these optional fields or the absence of an output schema. However, the core usage is fully explained, and the schema fills 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?
The schema already provides detailed descriptions for all parameters, including the mutual exclusivity of single-file vs. files[] modes. The description only reiterates 'one source_code file or multiple files entries' without adding new semantic 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?
Clearly states it generates an OpenAPI/Swagger specification from user-supplied API source code, distinguishing it from other generation tools by the specific output type.
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 supplies API source code and asks for an OpenAPI or Swagger specification,' giving a direct condition for when to select this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user supplies source code and asks for UML, Mermaid, sequence, class, component, or architecture diagrams. State-changing generation action: consumes AI credits, creates a generation, and optionally writes markdown to a Space after authorization. Use browser guidance for local uploads or full repository diagrams.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional generation name. | |
| filename | Yes | Filename for the source code. | |
| source_code | Yes | Source code to analyze. | |
| diagram_type | Yes | Class Diagrams, Sequence Diagrams, Use Case Diagrams, Activity Diagrams, Component Diagrams, State Diagrams, or Object Diagrams. | |
| save_to_space | No | Optional destination Space item. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses side effects beyond the annotations: 'consumes AI credits, creates a generation, and optionally writes markdown to a Space after authorization.' This is highly informative and goes beyond the readOnlyHint=false annotation, which only implies state-changing. It also mentions the need for authorization, setting accurate expectations 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 description is concise at three sentences, with the primary use case front-loaded in the first sentence. The second sentence covers side effects, and the third gives additional guidance. No unnecessary words or repetition; it is well-structured for quick 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 state-changing tool with a nested optional object and no output schema, the description covers the main behavioral aspects (credit consumption, generation creation, optional Space write) and the schema fully documents parameters. It does not explicitly mention what the tool returns (e.g., a generation ID), but this is not unusual and might be handled by follow-up tools. Slight omission but not a major gap, so a 4 is appropriate.
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 provides descriptions for all parameters (100% coverage), so the baseline is 3. The tool description adds no additional clarification or examples about parameters themselves, such as how to specify diagram_type or the relationship between filename and source_code. It does not exceed the schema-provided information, so it stays at the baseline score.
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: generate UML/Mermaid/sequence/class/component/architecture diagrams from user-supplied source code. It includes a specific verb 'generate' and resource 'UML diagram', and the usage context distinguishes it from other generation tools by referencing source code and specific diagram types.
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 tells when to use the tool: 'Use this when the user supplies source code and asks for UML, Mermaid, sequence, class, component, or architecture diagrams.' It also provides additional guidance for a specific scenario ('Use browser guidance for local uploads or full repository diagrams'), and notes that it is state-changing and requires authorization for optional Space writes. This gives clear direction on when and how to invoke it without needing to infer from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to view current AI writing guidelines, templates, strict mode, generator scope, or team-enforced generation preferences. Read-only: returns effective personal/team preferences and whether they are editable without changing settings.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Use this when the user wants to inspect an existing full-tree documentation preview before creating a Space. Read-only: returns repository details, tree titles, page counts, source-file counts, credit impact, and an acceptance hash for the numeric repository_id.
| Name | Required | Description | Default |
|---|---|---|---|
| repository_id | Yes | Required numeric ID of the imported repository that already has a generated full-tree documentation preview. Do not pass a Space ID, repository slug, provider URL, or Autopilot repository-link ID. |
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.
Use this when the user wants to read a specific generated output/result, inspect version metadata, see generated markdown, or choose a version for later actions. Read-only: returns the generation by numeric generation_id without changing it.
| Name | Required | Description | Default |
|---|---|---|---|
| generation_id | Yes | The numeric generation ID. Call list-generations first. | |
| include_source | No | Include the original source code/content. Defaults to false. |
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.
Use this when the user asks what changed in a Space, who changed settings, sync events, document actions, or recent activity. Read-only Enterprise feature: returns the Space activity/audit log newest first. Requires numeric space_id and Enterprise access.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of entries to return (default 50, max 500). | |
| since | No | ISO 8601 datetime. Only return entries created after this timestamp. | |
| space_id | Yes | The numeric ID of the space to read the audit log for. Call list-spaces first. |
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.
Use this when the user wants to read the full markdown content of a specific Space document/page after search or listing. Read-only: returns the selected document without changing content. Requires the document ID from list-space-documents, search-space-documents, or global-search.
| Name | Required | Description | Default |
|---|---|---|---|
| space_id | Yes | The numeric ID of the space containing the document. Call list-spaces first. | |
| document_id | Yes | The numeric ID of the document to retrieve |
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.
Use this when the user asks which DocuWriter.ai account is connected or whether it can run a generator. Read-only: returns the account name and a can_generate boolean without changing account data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Use this when the user wants to search documents across every accessible Space rather than one known Space. Read-only: returns matching titles, snippets, Space details, and URLs for a query without changing content.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (minimum 2 characters) | |
| per_page | No | Number of results to return (default 20, max 100) |
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.
Use this when the user wants to invite a teammate by email with an editor or viewer role. After authorization, this state-changing external action creates a pending invitation and sends one email; invitation acceptance occurs in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | Configured team role to grant, usually editor or viewer. Use list-team-members first to inspect available_roles. | |
| Yes | Email address to invite to the current team. Use list-team-members first if the user refers to an existing pending invitation or teammate by name. |
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.
Use this when the user asks to find generated outputs, generation history, previous results, archived items, or IDs for later generation actions. Read-only: lists visible personal/team generations and can include previews or full content without changing anything.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number. Defaults to 1. | |
| type | No | Optional generation type filter. Accepts numeric enum values or names like documentation, tests, swagger_api_docs, git_full_tree_documentation. | |
| archived | No | Whether to show archived generations. Defaults to false. | |
| per_page | No | Results per page, 1-100. Defaults to 20. | |
| include_content | No | Include full generated content instead of a preview. |
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.
Use this when the user asks which DocuWriter.ai generators are available or what inputs a generator requires. Read-only: returns generator identifiers, required inputs, credit behavior, Space output behavior, and browser-only setup boundaries without running a generator.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Use this when the user asks whether GitHub, GitLab, Bitbucket, or Azure DevOps is connected, or asks which imported repository records already exist. Read-only: returns provider status and browser-only connect/reconnect guidance without exposing credentials. Use repository-link tools for Space Autopilot links.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | No | Optional provider guidance filter: github, gitlab, bitbucket, or azure. | |
| include_guidance | No | Include browser-only connection guidance. Defaults to true. |
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.
Use this when the user wants to choose a repository from a connected GitHub, GitLab, Bitbucket, or Azure DevOps provider before creating an Autopilot link. Read-only external-provider lookup: fetches repository choices or returns reauthorization/browser guidance. Requires provider and space_id.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | Yes | github, gitlab, bitbucket, or azure. | |
| space_id | Yes | Numeric Space ID where the user is choosing a repository for Autopilot setup. |
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.
Use this when the user wants to browse a Space tree, list pages/docs/documents/folders, find numeric document or item IDs, or inspect structure before editing. Read-only: returns documents and folders for one numeric space_id without changing content.
| Name | Required | Description | Default |
|---|---|---|---|
| space_id | Yes | The numeric ID of the space to list documents from. Call list-spaces first. |
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.
Use this when the user asks which repositories are linked to a Space for Autopilot, repo sync, suggestion generation, trigger events, or recent sync activity. Read-only: returns configured repository links plus bounded sync status/activity without exposing raw provider payloads.
| Name | Required | Description | Default |
|---|---|---|---|
| space_id | Yes | Numeric Space ID whose Autopilot repository links should be listed. | |
| activity_limit | No | Maximum recent sync events per link. Defaults to 5, max 20. | |
| include_activity | No | Include recent repository sync status/activity. Defaults to true. |
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.
Use this when the user asks to see, choose, or look up their documentation Spaces, especially before using tools that need a numeric space_id. Read-only: returns accessible Spaces and does not change settings or documents.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Use this when the user wants to review pending, snoozed, done, high-confidence, or filtered Autopilot/repository-sync documentation suggestions for a Space. Read-only: returns suggestion inbox items and IDs for later apply/discard/snooze tools without changing documents.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of suggestions to return (default 50, max 200). | |
| status | No | Filter by suggestion status. Accepted values: pending (default), applied, discarded. | |
| batch_id | No | Optional. Scope results to a single numeric batch ID. | |
| space_id | Yes | The numeric ID of the space whose suggestions you want to list. Call list-spaces first. |
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.
Use this when the user asks who is on their team, which teammates or seats exist, what roles are available, whether pending team invitations exist, or what team-member actions they can perform. Read-only: returns the current team roster, pending invitations, available roles, capabilities, and invitation-acceptance guidance without changing state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Use this when the user asks what webhook events, event names, or callback triggers are available before creating or editing a webhook subscription. Read-only: returns supported event keys and labels without changing subscriptions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Use this when the user asks whether webhooks delivered, failed, retried, or what payload event logs exist for their webhook subscriptions. Read-only: returns bounded delivery log summaries for owned subscriptions. Use list-webhook-subscriptions first when a subscription ID is needed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows to return, 1-50. Defaults to 25. | |
| success | No | Optional success/failure filter. | |
| event_type | No | Optional webhook event key filter. | |
| subscription_id | No | Optional webhook subscription ID filter. |
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.
Use this when the user asks which webhooks, callback URLs, integration subscriptions, or event endpoints are configured. Read-only: returns owned webhook subscriptions without changing them. Use list-webhook-events to discover valid event keys.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Use this when the user wants to move, nest, unnest, reorder, or reposition a Space page/document, folder, or external link. State-changing: updates the item location/order directly after authorization. Requires numeric space_id and item_id, plus optional parent_id/order from list-space-documents.
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | Optional order value. | |
| item_id | Yes | Numeric Space item ID for the page, folder, or external link to move. | |
| space_id | Yes | Numeric Space ID containing the item to move or reorder. | |
| parent_id | No | Destination folder ID, or null for root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states that it is state-changing and updates location/order directly after authorization, which is useful behavioral context. The annotations already indicate non-read-only and non-destructive, so the added explanation about immediate side effects and required parameters is above baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with the primary use case front-loaded. No redundant or overly verbose content; every sentence contributes useful 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 four-parameter mutation with no output schema, the description covers what, when, required/optional parameters, and side effects. It does not explain edge cases like child items or order semantics, but this is not a significant gap given the schema and annotations.
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 already cover all four parameters, and the description reinforces that space_id and item_id are required while parent_id and order are optional. It adds extra semantic value by indicating that parent_id/order should come from list-space-documents.
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 ('move, nest, unnest, reorder, or reposition') and the resource ('Space page/document, folder, or external link'). It also identifies the target context with 'Use this when', making it easy to select over siblings like 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?
It explicitly defines when to use the tool with a concrete list of user intents. It does not explicitly mention alternatives or when-not-to-use cases, but the 'Use this when' phrasing provides strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user explicitly wants to remove an existing teammate and revoke their access to team Spaces. After authorization, this destructive action removes the specified member_id from the team; owners and the acting user cannot be removed.
| Name | Required | Description | Default |
|---|---|---|---|
| member_id | Yes | Numeric user/member ID to remove from the current team. Use list-team-members first when the user gives a name or email. |
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.
Use this when the user explicitly asks to submit feedback about DocuWriter.ai or its MCP integration. After authorization, this state-changing action records the supplied feedback in DocuWriter.ai internal feedback logs.
| Name | Required | Description | Default |
|---|---|---|---|
| feedback | Yes | The user feedback text (minimum 10 characters) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description transparently discloses that this is a state-changing action that 'records the supplied feedback in DocuWriter.ai internal feedback logs'. This aligns with the annotations (readOnlyHint=false, destructiveHint=true) and adds context about where the data goes, without any contradictions.
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 clear sentences. It conveys the trigger condition, the action type, and the outcome without any redundant 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 feedback-submission tool, the description provides all necessary context: when to use it, what it does, and what input it requires. No output schema is specified, which is acceptable for this action. The description is complete relative to the tool's simplicity.
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 'feedback' is described in the schema with its minimum length, and the tool description does not add further semantic detail beyond what the schema already provides. Since schema coverage is 100%, 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: submitting feedback about DocuWriter.ai or its MCP integration. It uses the specific verb 'submit' and identifies the resource, and there is no sibling tool with overlapping feedback functionality, so no differentiation is needed.
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 an explicit trigger condition: 'Use this when the user explicitly asks to submit feedback'. It also mentions the authorization requirement, giving clear guidance on when this tool should be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to unarchive, restore, or show an archived generation again in the active generation list. State-changing: restores the visible archived generation after authorization. Requires generation_id from list-generations with archived=true.
| Name | Required | Description | Default |
|---|---|---|---|
| generation_id | Yes | Generation ID to restore. Call list-generations with archived=true first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the tool is known to be state-changing but not destructive. The description adds useful behavioral context: it is state-changing, requires authorization, and restores the archived generation into the visible active list. This goes beyond the annotation defaults 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 concise sentences carry the trigger condition, the state-changing nature, the authorization requirement, and the parameter prerequisite. Everything is front-loaded and every clause earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter state-changing tool, the description is complete: it covers when to use it, what effect it has, the authorization note, and where to get the required ID. It does not describe the return value or error cases, but no output schema exists and the operation is simple enough that this is a minor 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%, and the single parameter generation_id is already described in the schema. The description adds the important prerequisite of calling list-generations with archived=true first, but this mostly restates the schema's parameter guidance rather than adding substantial new 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 uses specific verbs ('unarchive, restore, or show') tied to a clear resource ('archived generation') and outcome ('in the active generation list'). It clearly differentiates from sibling tools like archive-generation and get-generation by describing the restore action rather than creation, retrieval, or archiving.
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 exactly when to use the tool ('when the user wants to unarchive, restore, or show an archived generation again') and gives a prerequisite ('Requires generation_id from list-generations with archived=true'). It does not explicitly name alternatives or when not to use it, but the context 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.
Use this when the user explicitly asks to disconnect GitHub, GitLab, Bitbucket, or Azure DevOps. After authorization, this destructive action revokes the selected provider connection; it requires a provider key from the connection list.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | Yes | Provider to revoke: github, gitlab, bitbucket, or azure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description reinforces this with 'destructive action' and 'After authorization'. It adds context by noting a prerequisite (requires a provider key from the connection list), which is valuable for the agent to prepare the call. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: the first gives the trigger condition, the second states the action and prerequisite. The most critical information (when to use) is front-loaded, and every phrase 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 single-parameter destructive action with no output schema, the description covers when, what, and a key prerequisite. It does not describe the outcome or response format, but that is not essential for a tool that simply revokes a connection. The 'from the connection list' hint also guides the agent to retrieve the value from the appropriate sibling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the provider values and meaning. The description adds a note about 'a provider key from the connection list,' which hints at the source of the value, but this is marginal over 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?
States a clear verb+resource: revoking a provider connection, and explicitly names the supported providers (GitHub, GitLab, Bitbucket, Azure DevOps). Distinguishes from sibling tools like list-provider-connections by describing an action (revoke) rather than a query.
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 explicit when-to-use guidance: 'when the user explicitly asks to disconnect...' and lists the specific providers. It doesn't mention when not to use or alternatives, but the trigger condition is clear and leaves no ambiguity about appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to find pages, docs, documents, or content inside one specific Space. Read-only: searches the selected Space and returns matching document snippets without changing content. Requires numeric space_id from list-spaces.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination | |
| query | Yes | Search query (minimum 2 characters) | |
| per_page | No | Number of results per page | |
| space_id | Yes | The numeric ID of the space to search in. Call list-spaces first. | |
| highlight | No | Whether to highlight search terms in results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explicitly states 'Read-only' and 'without changing content', which aligns with the readOnlyHint annotation. It also describes the core behavior (searches and returns matching document snippets). No additional side effects or limitations are mentioned, but the description adds value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant information. It effectively communicates the purpose, read-only nature, and the key prerequisite without wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description adequately states that it returns 'matching document snippets'. Combined with parameter explanations, it provides sufficient context 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?
All 5 parameters have clear descriptions in the schema (100% coverage). The description adds extra context for space_id, specifying it must be numeric and obtained from list-spaces, which goes beyond the schema's basic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool 'finds pages, docs, documents, or content' within a specific Space, using a specific verb and resource. It also distinguishes the scope by emphasizing 'one specific Space' and requiring space_id from list-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?
Provides a clear when-to-use condition ('when the user wants to find... inside one specific Space') and a prerequisite (requires numeric space_id from list-spaces). However, it does not explicitly mention alternatives like global-search for cross-space searching, 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.
Use this when the user wants a specific version to become the current content of an existing generation. After authorization, this state-changing action applies version_number to the specified generation_id.
| Name | Required | Description | Default |
|---|---|---|---|
| generation_id | Yes | Generation ID to update. Call get-generation first to inspect available versions. | |
| version_number | Yes | Existing version number to mark as definitive. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates this is a state-changing action and that it applies a version to a generation, which aligns with the readOnlyHint=false annotation. It mentions authorization is required, adding context about side effects. It does not detail reversibility or failure modes, but the annotation destructiveHint=false covers some of that.
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-loaded with the primary intent. The phrase 'After authorization' is slightly redundant but does not bloat the text significantly. Overall, it is efficient 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?
For a simple two-parameter tool with no output schema, the description covers the main context: when to use it and what it accomplishes. It does not mention edge cases like invalid version numbers, but that is not required for basic usage. The sibling tool list helps contextualize its role among generation actions.
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 both parameters with identical text to the description. The description adds no new semantic detail beyond restating the parameter roles, so the baseline of 3 is appropriate since there is no additional clarification.
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: setting a specific version as the current content of an existing generation. It distinguishes this action from other generation-related tools by focusing on the version assignment.
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 specific version to become the current content. This provides clear guidance and implicitly differentiates from tools like update-generation or archive-generation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to postpone, remind later, or snooze one Autopilot/repository-sync documentation suggestion. State-changing: hides the pending suggestion until the specified date/time after authorization. Requires suggestion_id from list-space-suggestions and an until timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| until | Yes | Future date/time parseable by the platform. | |
| suggestion_id | Yes | Numeric Autopilot suggestion ID to snooze. Use list-space-suggestions first when needed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses state-changing behavior ('hides the pending suggestion until the specified date/time') and mentions an authorization requirement ('after authorization'), adding behavioral details 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?
Description is concise, front-loaded with the primary use case, and flows logically from purpose to state change to required inputs.
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 provides sufficient context: purpose, state-changing effect, authorization requirement, and parameter sourcing.
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 already cover both parameters (suggestion_id and until) with clear meaning; description adds only a slight reinforcement ('Requires suggestion_id from list-space-suggestions and an until timestamp') without introducing new semantic information.
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 tool's purpose with a specific verb ('snooze') and resource ('space suggestion'), and distinguishes from siblings by noting it handles a single suggestion (not bulk) and specifically targets 'Autopilot/repository-sync documentation suggestion'.
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 explicit usage conditions ('when the user wants to postpone, remind later, or snooze one...') and parameter requirements, but does not explicitly contrast with alternative sibling tools like apply or discard, though context implies this tool is for temporarily hiding rather than finalizing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to change AI writing guidelines, templates, strict mode, generator scope, or team enforcement. After authorization, this state-changing action updates personal or owner-managed team preferences; team-enforced settings can prevent member edits.
| Name | Required | Description | Default |
|---|---|---|---|
| template_text | No | Markdown template, max 12000 characters. | |
| guidelines_text | No | Text guidelines, max 4000 characters. | |
| strict_template | No | Strict template mode. | |
| enforce_for_team | No | Team-owner-only enforcement flag. | |
| use_team_settings | No | Preference scope to update: personal or team. Team scope requires owner authorization. | |
| apply_to_generators | No | GenerationType integer values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description labels the action as 'state-changing', which aligns with readOnlyHint=false. It adds context beyond the annotations by mentioning authorization requirements and the possibility that team-enforced settings can prevent member edits, but does not detail success/failure 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 two sentences, front-loaded with the primary use case, and lists the changing fields succinctly. No unnecessary fluff.
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 key context (authorization, team enforcement, scope) and the main purpose. Lacks details about successful update behavior (e.g., return value) but that is not required given no output schema. The description is sufficient for an agent to decide whether to invoke 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?
All 6 parameters have descriptions with some added constraints (e.g., max lengths, permission context, scope). However, 'apply_to_generators' is described only as 'GenerationType integer values', which is vague without a reference to what GenerationType means, and there is no clarification that all fields are optional in a patch-like update.
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: changing AI writing guidelines, templates, strict mode, generator scope, or team enforcement. It uses a specific verb ('change') and resource (AI preferences), and implicitly distinguishes from the read-only sibling get-ai-preferences.
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 when to use it ('Use this when the user wants to change...') and includes important caveats about authorization and team-enforced settings preventing member edits. This gives clear guidance for choosing this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to rename an existing generated result. After authorization, this state-changing action updates the filename for the specified generation_id.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | New generation filename, up to 255 characters. | |
| generation_id | Yes | Generation ID to update. Call list-generations first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already state readOnlyHint=false and destructiveHint=false, so the description's 'state-changing action' is consistent but not additive. It adds an 'After authorization' nuance and clarifies the mutation is on the filename, yet it doesn't disclose side effects, reversibility, or permissions beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with a clear first-sentence trigger and a second sentence stating the action. There is minor redundancy ('state-changing action' adds little), but it overall remains short and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with full schema descriptions and no output schema, the description provides enough context about what is renamed and when to use it. The only minor gap is the absence of any mention of effects on existing references (e.g., share links), but not enough to mark it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already defines both parameters with descriptions and coverage is 100%. The tool description doesn't add much meaning beyond the schema, and the schema's note to call list-generations first effectively covers the important prerequisite.
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 — rename an existing generated result — and identifies the exact effect: updating the filename for a generation_id. It distinguishes its purpose from related actions like archive or restore, though it doesn't explicitly name sibling alternatives, so it misses the highest bar.
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 an explicit use-this-when condition: 'when the user wants to rename an existing generated result.' That gives clear context for invocation, but it doesn't mention when not to use it or directly compare with sibling tools like set-generation-definitive-version, which would warrant a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to rename a Space, edit its description, make it public/private, publish/unpublish it, or change its public slug. State-changing: updates manageable Space settings after authorization. Requires numeric space_id from list-spaces.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New Space name when the user wants to rename the Space. | |
| slug | No | Public slug to use when the Space is published or made public. | |
| space_id | Yes | Numeric Space ID to update. Use list-spaces first when the user gives a Space name. | |
| is_public | No | Public visibility flag. | |
| description | No | New Space description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it is 'state-changing' and the annotations confirm readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description does not contradict these annotations and adds minimal extra context about side effects. Given the annotations already convey the behavioral traits, the description meets the baseline but does not add significant transparency beyond what is already provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that lists all relevant actions and the required parameter. It is efficiently structured, with no fluff or redundancy. The key information is front-loaded, making it easy to parse quickly.
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 this is a mutation-only tool, and the description explains the operations and the prerequisite for space_id. It does not need to elaborate on return values. It is sufficiently complete for an agent to use it correctly in conjunction with the sibling tools and list-spaces.
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 covers 100% of parameters with descriptions, and the description adds practical guidance (e.g., space_id should come from list-spaces). The per-parameter descriptions align with the main description, making the semantics clear. Slight boost because the tool description reinforces the parameter usage, especially for the required space_id.
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 ('update') and resource ('Space'), and enumerates the exact mutations it performs (rename, edit description, make public/private, publish/unpublish, change slug). This distinguishes it from sibling tools like create-space and delete-space, so an agent can identify the correct tool without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool 'when the user wants to rename, edit, etc.' and notes that space_id must be a numeric ID from list-spaces, providing clear guidance. However, it does not explicitly mention when not to use this tool, though the sibling list and specific action list imply alternatives. Minor gap, but still above average.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to replace or update the markdown content/title of an existing Space document. State-changing and content-destructive: writes the new document content directly after authorization. Read the document first when preserving existing content matters.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | The type of content being provided (blank or markdown) | |
| title | No | The new title of the document | |
| content | No | The new content of the document (markdown or plain text) | |
| space_id | Yes | The numeric ID of the space containing the document. Call list-spaces first. | |
| parent_id | No | The numeric ID of the parent folder (null to move to root) | |
| document_id | Yes | The numeric ID of the document to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is state-changing and content-destructive, aligning with the destructiveHint annotation. However, it omits the ability to move the document via the parent_id parameter, which is a significant behavioral effect not covered by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise, and front-loaded with the use case. It does not contain unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's six parameters and lack of output schema, the description provides essential context but misses the move behavior via parent_id. It also doesn't mention idempotency or return values, but these are less critical.
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 all six parameters (100% coverage), so baseline is 3. The description adds minimal detail beyond restating content/title, and does not clarify the role of parent_id or type.
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 (replace or update markdown content/title of an existing Space document) and identifies the resource type, distinguishing it from siblings like create-space-document and get-space-document. It also includes a conditional instruction to read first when preserving content.
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 'Use this when...' and provides a conditional guidance about reading first. However, it does not explicitly contrast with create-space-document or other update tools, though the 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.
Use this when the user wants to rename or edit a Space page/document, folder, or external link, including markdown content, external URL, or parent folder changes. State-changing: updates the Space item directly after the MCP client authorizes the call. Requires numeric space_id and item_id from list-space-documents.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | New title when the user wants to rename the Space item. | |
| content | No | New markdown content for page items. | |
| item_id | Yes | Numeric Space item ID for the page, folder, or external link to update. | |
| space_id | Yes | Numeric Space ID containing the item to update. Use list-spaces/list-space-documents first when needed. | |
| parent_id | No | New parent folder ID. | |
| external_url | No | New URL for external links. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states that the tool is 'State-changing' and that it 'updates the Space item directly after the MCP client authorizes the call'. This adds context beyond the annotations (readOnlyHint=false, destructiveHint=false) by clarifying the authorization requirement, though it could further detail potential 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 concise, consisting of two sentences that directly convey the tool's purpose, usage, and required parameters. There is no redundancy or extraneous information, making it 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?
Given there is no output schema, the description does not need to address return values. It provides sufficient context for invoking the tool, including prerequisites (space_id and item_id from list-space-documents) and the authorization note. It could mention what happens with null parameters, but the schema already clarifies that, so the description is reasonably 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 100% of parameters with descriptions, including the nullable properties. The description mentions content, external URL, and parent folder changes, but these are already described in the schema, so no additional meaning is added. Thus, 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 verb 'rename or edit' and the resource 'Space page/document, folder, or external link', making the tool's purpose distinct. It also enumerates specific editable attributes (markdown content, external URL, parent folder), which removes ambiguity about what the tool does.
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 begins with 'Use this when...' and specifies the required identifiers (space_id and item_id) and their source (list-space-documents). This gives clear, actionable guidance on when and how to invoke the tool, satisfying the explicit usage criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to change an existing Space Autopilot repository link. After authorization, this state-changing external action updates its branch, triggers, path filters, AI context, notifications, or auto-apply settings and requires Enterprise access.
| Name | Required | Description | Default |
|---|---|---|---|
| branch | No | Repository branch name that Autopilot should monitor after the update. | |
| link_id | Yes | Numeric repository link ID to update. Use list-space-repository-links first when needed. | |
| space_id | Yes | Numeric Space ID containing the Autopilot repository link to update. | |
| path_filters | No | Optional path filters. | |
| trigger_events | No | push and/or pr_merge. | |
| auto_apply_enabled | No | Enterprise auto-apply flag. | |
| ai_context_instructions | No | Optional AI instructions. | |
| auto_apply_threshold_pct | No | Auto-apply threshold percent from 95 to 100. | |
| notify_on_new_suggestions | No | Email notification flag. | |
| notification_channels_input | No | Notification channel settings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly mentions 'state-changing external action' and 'requires Enterprise access', adding behavioral context beyond the annotations. It also notes 'After authorization', clarifying that authorization is needed.
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 front-loads the purpose and includes key conditions. There is no redundant or extraneous 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 provides essential context such as the need for authorization and Enterprise access, and the state-changing nature. While it doesn't detail return values or side effects, the absence of an output schema and the focus on modification make it reasonably complete for an update 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 provides full descriptions for all 10 parameters, covering their meanings and constraints. The tool description does not add further semantic detail beyond what is already in the schema, so it meets the baseline for high 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 updates an existing Space Autopilot repository link, using the specific verb 'change' and resource. It distinguishes from sibling tools like create, delete, or enable/disable by focusing on modification.
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 indicates when to use it ('when the user wants to change an existing link'), implying it is for modifications rather than creation or deletion. It does not explicitly compare with alternatives, but the wording provides sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to change an existing teammate between configured editor and viewer roles. After authorization, this state-changing action updates the specified member_id; the team owner role cannot be changed.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | Configured destination role key, usually editor or viewer. Use list-team-members first to inspect available_roles. | |
| member_id | Yes | Numeric user/member ID whose role should change. Use list-team-members first when the user gives a name or email. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description notes that authorization is required and that the team owner role cannot be changed, adding useful behavioral context beyond the annotations. It also explicitly labels the action as state-changing, consistent with readOnlyHint=false.
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 with no redundancy. It front-loads the primary use case and packs constraints efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple role-update tool, the description covers the purpose, usage context, authorization requirement, and an important restriction (owner cannot be changed). No output schema is needed for this action.
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 meaningfully: member_id is identified as a numeric user/member ID with a pointer to list-team-members for resolving names/emails, and role is explained as a configured destination role key with instruction to inspect available_roles. Schema coverage is 100%.
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 (change/update role), the resource (existing team member), and the specific scope (between editor and viewer roles). It distinguishes from sibling tools like invite-team-member and remove-team-member by focusing on role updates.
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 to change an existing teammate') and provides a prerequisite by referencing list-team-members to inspect available roles. This gives clear guidance on the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to change a webhook endpoint URL, subscribed events, active/inactive status, or metadata. State-changing external action: updates the owned webhook subscription after authorization. Requires subscription_id from list-webhook-subscriptions; use list-webhook-events for valid keys.
| Name | Required | Description | Default |
|---|---|---|---|
| events | No | Event keys from list-webhook-events. | |
| metadata | No | Optional metadata object to replace or store with the webhook subscription. | |
| is_active | No | Whether the subscription is active. | |
| webhook_url | No | HTTP/HTTPS webhook endpoint. | |
| subscription_id | Yes | Webhook subscription ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it is a 'State-changing external action' and that it occurs 'after authorization,' which adds context beyond the annotations. Since annotations already indicate readOnlyHint=false and destructiveHint=false, the description's additional note about authorization and external impact enhances transparency without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of three clear sentences. It front-loads the primary purpose ('change a webhook...') and immediately follows with essential constraints ('Requires subscription_id...', 'use list-webhook-events...'). No unnecessary words or redundant 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's moderate complexity (5 parameters, including a nested object) and lack of output schema, the description covers all necessary context: what it does, when to use it, required inputs, and references to related tools. It provides enough information for an agent to select and invoke the tool correctly without additional documentation.
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 descriptions for all parameters. The description adds context by telling users to obtain subscription_id from list-webhook-subscriptions and to use list-webhook-events for valid keys, which helps understand the relationships between parameters and other tools. This goes beyond the schema's basic definitions.
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 change a webhook endpoint URL, subscribed events, active/inactive status, or metadata. It explicitly mentions 'updates the webhook subscription' and distinguishes from create/delete by focusing on modifications. The reference to requiring subscription_id from list-webhook-subscriptions and using list-webhook-events for valid keys further clarifies its role among related 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 explicitly states when to use the tool ('Use this when the user wants to change...') and provides prerequisites: 'Requires subscription_id from list-webhook-subscriptions' and 'use list-webhook-events for valid keys.' This gives clear guidance on when to invoke it and what to prepare, which is more than sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add-generation-to-spaceapply-space-suggestionarchive-generationbulk-manage-space-suggestionscancel-team-invitationcopy-space-itemcount-space-suggestionscreate-generation-share-linkcreate-space-documentcreate-space-itemcreate-space-item-share-linkcreate-space-repository-linkcreate-webhook-subscriptiondelete-space-documentdelete-space-itemsdelete-space-repository-linkdelete-webhook-subscriptiondisable-space-repository-linkdiscard-space-suggestionenable-space-repository-linkexport-space-items-markdowngenerate-and-add-documentationgenerate-codebase-documentationgenerate-full-tree-documentationgenerate-repository-documentationgenerate-repository-readmegenerate-repository-release-notesget-ai-preferencesget-full-tree-documentation-previewget-generationget-space-activity-logget-space-documentinvite-team-memberlist-generationslist-generatorslist-provider-connectionslist-provider-repositorieslist-space-repository-linkslist-space-suggestionslist-team-memberslist-webhook-eventslist-webhook-logslist-webhook-subscriptionsmove-space-itemremove-team-memberreport-feedbackrestore-generationrevoke-provider-connectionset-generation-definitive-versionsnooze-space-suggestionupdate-ai-preferencesupdate-generationupdate-space-documentupdate-space-itemupdate-space-repository-linkupdate-team-member-roleupdate-webhook-subscriptioncreate-spacedelete-spacegenerate-code-commentsgenerate-code-documentationgenerate-code-optimizationgenerate-code-testsgenerate-language-conversiongenerate-swagger-apigenerate-uml-diagramget-user-infoglobal-searchlist-space-documentslist-spacessearch-space-documentsupdate-spaceVersioned documentation registry and semantic search for AI tools and coding assistants.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Add one secure layer between your agents and this server.
