docuwriter

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

Annotations already declare it non-read-only and non-destructive; the description adds real context beyond them by flagging the authorization step and the visibility consequence ('adding it to a public Space makes the content publicly accessible'), which is the kind of side-effect an agent cannot infer from 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?

Front-loaded with the usage trigger and packed into two sentences with no filler. The trailing parameter list is mildly redundant given full schema coverage but still terse.

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 create-style mutation with no output schema, it covers the essential concerns: state change, authorization, public-visibility risk, and required inputs. Only the absence of any error or idempotency note keeps it out of the top band.

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 four parameters including required status and the list-spaces/list-generations preconditions. The description only restates which fields are required/optional, adding no syntax or semantics 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 and resource ('save, publish, or add an existing generated output/result into a documentation Space') and scopes it to existing generations, which separates it from siblings like generate-and-add-documentation 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?

Gives a clear trigger condition ('Use this when the user wants to save, publish, or add an existing generated output'). It does not name an alternative or a when-not case, but the 'existing' qualifier implicitly routes newly-generated content elsewhere.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is known; the description goes beyond them by stating what actually happens ('writes the suggested content to the target Space document and marks the suggestion applied') and that authorization is required. It stops short of describing reversibility or what happens on a failed/unauthorized apply.

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

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

Three short sentences, front-loaded with the trigger condition, then the behavioral warning, then the prerequisite. No filler, though the destructive warning and the 'apply or accept' pairing are mildly redundant with 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 single-parameter mutation with no output schema, the description covers the trigger, the side effects, the authorization requirement, and the prerequisite tool. The only gap is that it says nothing about what the caller receives back or what happens if the suggestion is stale or already applied.

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

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

With one parameter at 100% schema coverage the baseline is 3, but the description adds provenance the schema lacks: it tells the agent the suggestion_id must be obtained from list-space-suggestions rather than guessed. It adds no format or validation detail beyond that.

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 pair ('apply or accept') and resource ('one pending Autopilot/repository-sync documentation suggestion'), with the scope qualifier 'one' that separates it from bulk-manage-space-suggestions. An agent can distinguish it from discard-space-suggestion and snooze-space-suggestion without opening any schema.

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

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

Explicitly gives the trigger condition ('when the user wants to apply or accept one pending... suggestion') and names the source of the required input ('Requires suggestion_id from list-space-suggestions'). It does not explicitly exclude alternatives such as bulk-manage-space-suggestions for multiple suggestions, but the singular scope makes that inference safe.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the write-but-non-destructive profile is already covered. The description adds genuinely new context: it is 'state-changing', the archive happens 'after authorization', and the generation is not deleted. This is useful beyond the structured hints.

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

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

Two sentences, no waste. The user-intent trigger and the non-deletion guarantee are front-loaded, and the prerequisite is compactly appended.

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, non-destructive mutation with annotations covering the safety profile and no output schema, the description supplies purpose, trigger, prerequisite, and authorization context. It lacks only explicit undo/restore guidance, 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?

Only one parameter and schema description coverage is 100%, so the schema already fully documents generation_id. The description reinforces the list-generations prerequisite but adds no format or syntax detail, so the baseline 3 applies.

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

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

States a specific verb+resource (archive an existing generation) and immediately scopes it as removing it from the active list 'without deleting it'. That negative clause distinguishes it from destructive siblings like delete-space-items and from restore-generation's inverse operation.

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

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

Opens with an explicit trigger ('when the user wants to archive, hide, or remove') and states the prerequisite that generation_id must come from list-generations. It does not name restore-generation as the explicit undo path, so the when-not guidance is implied rather than stated.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, yet the description still adds real value: it specifies what each branch destroys (bulk apply mutates multiple Space documents; bulk discard removes suggestions from active review after authorization) and states the Enterprise access requirement. This is exactly the beyond-annotation context the bar asks for.

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

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

Three sentences, front-loaded with the trigger, followed by behavioral risk and then prerequisites. No filler; each sentence carries information an agent needs before calling.

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

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

For a two-parameter destructive mutation with no output schema and full annotation coverage, the definition supplies trigger, risk, prerequisites, and ID provenance. Nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, making 3 the baseline. The description goes further by explaining the operational consequence of each action value ('apply' mutates documents, 'discard' ends active review), which the schema's flat string field does not convey.

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

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

States a specific verb+resource: bulk apply or discard multiple Autopilot/repository-sync suggestions at once. The 'multiple ... at once' phrasing directly distinguishes it from the singular apply-space-suggestion and discard-space-suggestion siblings, so an agent can route correctly without opening a schema.

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

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

Gives an explicit trigger ('Use this when the user wants to apply or discard multiple ... at once'), a prerequisite (suggestion IDs from list-space-suggestions), and a gating condition (bulk apply requires Enterprise access). Alternatives are implied by the bulk-vs-single framing and the named source tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is largely covered. The description still earns credit by adding two things not in structured data: the authorization prerequisite ('After authorization') and the concrete effect that the invitation can no longer be accepted.

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, zero filler, trigger condition front-loaded before the effect statement. Nothing could be cut without losing information.

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

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

For a single-parameter mutation with full schema coverage, no output schema, and annotations carrying the destructive profile, the description supplies everything an agent needs: trigger, precondition, target, and consequence.

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 schema itself already tells the agent to use list-team-members first when given an email. The description only repeats that invitation_id is the target of the cancellation, adding no new format, range, or resolution guidance beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource ('cancel a pending team invitation') plus a temporal qualifier ('before it is accepted') that separates it from removing an existing member. It does not name the sibling alternatives (remove-team-member, invite-team-member) that would let an agent route without inference.

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

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

Opens with an explicit trigger: 'Use this when the user wants to cancel a pending team invitation before it is accepted.' The pending-only condition implicitly excludes already-accepted members, but the description never states the negative case or points to the tool for accepted members.

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

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

Annotations establish the write profile (readOnlyHint=false, destructiveHint=false), and the description usefully adds that the operation is state-changing, requires prior authorization, recursively copies children, and that copies landing in a public target Space are publicly accessible. It does not address name-collision handling or whether the copy is atomic, so it is strong but not complete.

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-loads the when-to-use clause, then behavior, then parameters. The final parameter sentence largely duplicates what the schema already encodes at 100% coverage, which is minor redundancy rather than bloat.

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 no output schema, the description covers the trigger, the authorization precondition, and the public-visibility consequence — enough to call it correctly. It omits whether new item IDs are returned for follow-up calls, which is the main remaining gap.

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

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

Schema description coverage is 100%, so all four parameters are already documented, and the description only restates which are required versus optional without adding format, ID-sourcing, or null-handling detail. Baseline 3 applies when the schema carries 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?

States a specific verb (copy/duplicate/clone), the resource (Space page/document, folder, external link) and the scope (including its children), and places the result precisely (into another Space). This clearly separates 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?

The lead clause gives a clear trigger condition and lists the synonyms a user might say, which aids selection. It stops short of naming the natural alternative (move-space-item) or stating when not to use it, so it is contextual but not exhaustive.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, yet the description still adds real behavioral content: results are grouped counts by status, and it explicitly states nothing is changed. It does not describe the groupings' keys or ordering, but the add-on value over annotations is genuine.

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

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

Three tight sentences: trigger, behavior/scope, parameter. Purpose and the read-only guarantee are front-loaded with no filler.

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

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

For a single optional-param counting tool with clear annotations and no output schema, the description covers trigger, safety, output nature (grouped counts) and filtering adequately. Exact count keys are left unspecified, which is a minor gap given there is no output schema.

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

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

Schema coverage is 100% and the schema already says 'Optional Space filter.' The description only restates this and adds 'numeric', so it contributes little beyond the structured field. Baseline 3 applies.

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

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

States a specific verb (count) plus resource (space suggestions) and enumerates the status buckets it tallies, which clearly separates it from list-space-suggestions. It stops short of naming the sibling it supersedes, so the distinction is implied rather than explicit.

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

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

Gives an explicit trigger: 'Use this when the user asks how many ... suggestions are pending, snoozed, done, high-confidence, or waiting for review.' No when-not or alternative routing is offered, but the trigger condition is unambiguous.

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

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

Annotations already flag readOnlyHint=false and openWorldHint=true, and the description adds value beyond them: it discloses that the action is state-changing, produces a public URL, is gated by authorization, and returns a signed link. It stops short of describing revocation or persistence details.

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

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

Three tight sentences, front-loaded with the 'Use this when...' trigger, followed by behavior and prerequisites. No filler, though the second sentence slightly overlaps with annotation information.

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

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

For a two-parameter mutation with no output schema, the description covers trigger, mutating nature, authorization, and the returned signed link. Only revocation/lifecycle details are absent, which is minor.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: generation_id must be an owned generation sourced from list-generations, and expiration is optional. This ownership/provenance constraint 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?

States a specific verb+resource: creates a signed public share link for an existing generation/result. It is clearly distinguishable from the sibling create-space-item-share-link because it operates on a generation rather than a 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?

Gives a clear trigger condition ('when the user wants to share an existing generated output') and points to list-generations as the source of the required generation_id. It does not explicitly name alternatives or when-not-to-use, but the context is unambiguous.

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

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

Goes beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing that the call is state-changing, that creation happens after MCP client authorization, and that is_public=true exposes the Space publicly. It omits error behavior such as duplicate-name or duplicate-slug handling, which matters 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?

Three compact sentences, front-loaded with the usage trigger followed by behavioral notes. Minor redundancy in 'State-changing: creates the Space directly', but no filler or repetition that obscures the key facts.

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

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

For a 4-parameter create tool with annotations but no output schema, the description covers the trigger, required input, optional inputs, authorization flow, and the visibility side effect. It lacks any indication of what is returned or how creation failures are surfaced, which would round it out.

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

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

Schema description coverage is 100%, so all four parameters are already documented, and the description largely restates them ('Requires a Space name and may include description, public visibility, and slug'). The only added nuance is the consequence of is_public=true, which is close to a restatement of the field's own 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 and resource ('create a new documentation Space or knowledge base container'), which is the container-level create that distinguishes it from siblings like create-space-document and create-space-item. An agent can identify the operation without opening the schema.

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

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

'Use this when the user wants to create a new documentation Space' gives a clear triggering condition. It does not, however, name an alternative or state when NOT to use it (e.g. when the user instead wants to add an item to an existing Space), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is partly covered. The description adds genuinely new context: it is state-changing, creates the document directly after authorization, and that content in a public Space becomes publicly accessible. It does not address duplicate-on-retry behavior, which matters given idempotentHint=false, but the added value is real.

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?

Four compact sentences, each earning its place, with the trigger condition front-loaded before the requirements and the sibling disambiguation. No filler or restatement of the title.

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

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

Covers trigger, alternatives, required inputs, mutation semantics, and the public-visibility implication for a five-parameter creation tool with full schema coverage. The one gap is that no output schema exists and the description never indicates what comes back (e.g., the created document's ID), which an agent may need for follow-up calls.

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

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

Schema description coverage is 100%, so all five parameters including path folder-creation and parent_id are already documented in the schema. The description only restates the three required fields and adds no format, syntax, or interaction detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource: create a markdown document/page in a Space from provided content. It explicitly contrasts itself with the closest sibling, create-space-item, noting that one handles folders and external links, so an agent can route without opening either schema.

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

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

Gives an explicit trigger ('when the user wants to create a markdown document/page in a Space') and an explicit exclusion with the alternative named ('Use create-space-item for folders or external links'). Prerequisites (space_id, title, content) are also stated.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the description carries extra weight by stating the operation is state-changing, happens directly after authorization, and that content placed in a public Space becomes publicly accessible. That last point is a real consequence not derivable from the schema or annotations, though conflict/overwrite behavior is still unstated.

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

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

Two sentences, front-loaded with the use case and followed by the state-changing warning and visibility caveat. No filler, no restatement of the title, and every clause carries actionable 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 7-parameter mutation tool with no output schema and rich annotations, the description covers purpose, prerequisites, side effects, and visibility risk. It stops short of describing failure modes (duplicate titles, invalid parent_id) or permission requirements beyond the vague "after authorization."

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a conditional relationship the schema does not express: content or URL is required "when relevant" depending on item type, even though external_url and content are both optional in the schema. It also restates the key required inputs (numeric space_id, type, title), reinforcing them without redundancy.

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

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

The description names a specific verb and resource set (create a Space page/document, folder, or external link) scoped to an existing Space, so an agent immediately knows what the tool produces. It does not, however, differentiate itself from the close sibling create-space-document, which appears to overlap in scope.

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

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

"Use this when the user wants to create a Space page/document, folder, or external link inside an existing Space" gives clear activation context tied to user intent. No exclusions or named alternatives are offered, so an agent cannot tell from the text why it would pick this over create-space-document or create-space-repository-link.

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

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

Beyond the annotations, the description discloses that this is a state-changing public-link action, that it returns a signed public share link, and that authorization/owned Space access is required. It does not contradict the annotations, though it omits details such as whether existing links are reused or revoked.

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 efficient sentences, front-loading the usage trigger before the behavioral details. Every sentence adds useful information without padding.

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 3-parameter, no-output-schema tool, the description covers the trigger, the state-changing nature, authorization requirements, and the returned signed link. Minor remaining gaps, such as exact response shape or behavior when links already exist, keep it from being fully complete.

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

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

Schema description coverage is 100%, so the schema already documents space_id, item_id, and expires_in_minutes in detail. The description repeats the required parameters and adds the idea of owned Space access, but adds little parameter-level semantics 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 states a specific verb and resource: creating a public share link for Space pages/documents, folders, or external links. It is clear what the tool does, though it does not explicitly contrast itself with the similar sibling create-generation-share-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?

It gives a clear triggering condition: "Use this when the user wants to share a Space page/document, folder, or external link with a public URL." It does not state when not to use it or name alternatives, so it falls short of full alternative routing.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false. The description adds real value beyond that: it labels the operation a 'state-changing external action', names the authorization prerequisite, and flags Enterprise access. It doesn't describe irreversibility or failure modes, but it meaningfully extends the annotation profile.

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

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

Two sentences, zero filler, with the usage trigger front-loaded ahead of the behavioral and access notes. Every clause earns its place.

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

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

For an 11-parameter, 9-required mutation tool with a nested object and no output schema, the description covers purpose, trigger, prerequisite, and access scope adequately. The detailed parameter contract is fully handled by the 100%-covered schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so all 11 parameters are documented in the schema, setting the baseline at 3. The description names feature groups (triggers, path filters, notifications, auto-apply settings) that map onto parameters, but adds no syntax, format, or constraint detail 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 states a specific verb and resource: link an authorized provider repository to a Space for Autopilot sync. It cleanly distinguishes itself from siblings like list-space-repository-links, update-space-repository-link, and delete-space-repository-link, so an agent can route correctly without opening a schema.

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

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

It gives an explicit triggering condition ('Use this when the user wants to link...') plus a prerequisite ('After authorization') and an access gate ('requires Enterprise access'). It stops short of naming alternatives such as update-space-repository-link, but the context is clear.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the state-changing external nature is partly covered; the description reinforces it and adds the non-obvious detail that creation happens "after authorization." The note that test dispatch is unavailable further constrains behavior, though return payload and duplicate/error handling are not described.

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

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

Three tight sentences, front-loaded with the trigger condition and followed by constraints; no filler. The synonym list is slightly long but serves discovery matching, so it earns its place.

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

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

With no output schema, the description covers purpose, prerequisites, and authorization context sufficiently to invoke correctly. It does not say what the tool returns or how duplicate URLs are handled, leaving a small gap for a creation 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%, so all three parameters are already documented in the schema; the description only repeats the event-key sourcing (list-webhook-events) that the events parameter description already states. Baseline 3 is correct — no additional syntax or format meaning is layered on.

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

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

States a specific verb+resource (create a webhook subscription) and enumerates the synonyms an agent may encounter in user phrasing (callback URL, n8n/Zapier endpoint, integration subscription). This cleanly distinguishes it from the update-, delete-, and list-webhook 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?

Explicit triggering condition ("Use this when the user wants to add a webhook") plus a prerequisite route to a named sibling ("Use list-webhook-events first for valid event keys") and a scope exclusion ("webhook test dispatch is not exposed"). When-to-use, ordering, and out-of-scope are all stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond that: it states this removes a public Space and its public content, and that removal happens after MCP client authorization. It does not describe irreversibility or recovery options, which would push it higher.

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 usage condition, followed by the destructive scope and prerequisite. No filler, though the closing 'not for deleting individual pages' partially restates the 'whole Space' framing.

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

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

For a single-parameter destructive tool, the description covers trigger, exclusion, prerequisite source, and destruction scope, which is sufficient given annotations carry the safety profile and no output schema is needed. Missing only recovery/undo context.

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

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

Schema coverage is 100% and the single space_id parameter is fully documented in the schema ('Numeric Space ID to delete. Use list-spaces first...'). The description's 'Requires numeric space_id from list-spaces' largely repeats the schema, so it adds no syntax or format detail beyond it. Baseline 3 applies.

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

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

States a specific verb+resource ('delete a whole documentation Space') and disambiguates from siblings in the same family (delete-space-document, delete-space-items) by explicitly excluding individual pages. An agent can pick this tool without opening any schema.

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

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

Gives an explicit trigger ('when the user explicitly wants to delete a whole documentation Space') and an exclusion ('should not be used for deleting individual pages'), plus the prerequisite of obtaining space_id from list-spaces. It lacks naming the exact alternative tool, so routing is implied rather than direct.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is known. The description adds genuine context beyond them: deletion happens 'directly after authorization' and includes removal 'from public Space content'. It does not mention irreversibility or propagation effects, but the additions are substantive.

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

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

Three sentences, front-loaded with the trigger condition, then the behavioral warning, then the parameter source and the sibling alternative. Every sentence carries distinct information and there is no filler.

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

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

For a two-parameter destructive delete with no output schema, the description covers trigger, behavior, parameter sourcing, and the disambiguating alternative. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both space_id and document_id are already documented, making 3 the baseline. The description adds only a provenance hint that document_id comes from list-space-documents or search results, with no format or ID-sourcing detail beyond that.

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

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

States a specific verb and resource ('delete one existing Space document/page') and immediately differentiates from siblings by naming delete-space-items for folders or bulk deletion. An agent can distinguish it from create-space-document, update-space-document, and get-space-document without opening any schema.

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

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

Explicitly states when to use it ('when the user explicitly wants to delete one existing Space document/page') and names the alternative for the adjacent case (delete-space-items for folders or bulk item deletion). It also tells the agent where to source the document ID (list-space-documents or search results), removing all inference.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds genuine context beyond that: deletion happens directly after MCP client authorization, and it can affect items publicly visible in a public Space. It omits whether deletion is reversible or recoverable.

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

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

Three tight sentences with the destructive warning and the item types front-loaded; the prerequisite sentence closes it cleanly. No filler, though it is slightly denser than it needs to be.

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 is the only source of return/side-effect information, and it adequately covers the destructive nature, authorization requirement, and parameter provenance. A brief note on reversibility would close the remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by tying item_ids to their source (list-space-documents) and confirming space_id is numeric, giving the agent a workflow hook the schema alone does not provide.

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

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

States a specific verb (delete) plus the resource classes it handles (Space pages, documents, folders, external links) and scopes them to a Space. This distinguishes it from delete-space (whole space) and delete-space-document (single document), though it doesn't name those siblings explicitly.

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

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

Opens with an explicit trigger ("Use this when the user wants to delete one or more...") and tells the agent where the required IDs come from (list-space-documents). No explicit when-not statement or named alternative, which keeps it just below a 5.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond that: authorization ordering, a possible provider webhook side effect, and the Enterprise/manageable-Space permission requirements.

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

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

Three tight sentences with the purpose front-loaded and consequences and prerequisites following. No filler, though the sentences are quite densely packed.

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

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

No output schema exists but none is needed for a delete operation, and annotations carry the safety profile. Permission prerequisites and the webhook side effect are disclosed; the definition is complete enough 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?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description only restates that space_id and link_id are required, adding no syntax, format, or discovery guidance beyond the schema's own 'use list-space-repository-links first' hint.

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

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

States a specific verb+resource: removes an Autopilot repository link from a Space. This clearly separates it from siblings like create-space-repository-link, update-space-repository-link, and importantly disable/enable-space-repository-link, though it doesn't explicitly name the non-destructive 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?

Gives an explicit trigger condition ('when the user wants to remove an Autopilot repository link from a Space'). It does not state when-not to use it, e.g. when disable-space-repository-link is the better fit for temporary deactivation — a notable omission given the sibling set.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is known. The description still adds meaningful context beyond them: 'deletes the owned subscription after authorization' discloses an authorization prerequisite and ownership scoping, and it clarifies that test dispatch is unavailable.

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

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

Three short sentences, front-loaded with the trigger condition and the destructive nature. Every sentence carries distinct information — usage, safety/auth, and an exclusion — with no filler.

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

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

For a one-parameter destructive tool with no output schema, the definition covers purpose, destructiveness, authorization requirement, the source of the required ID, and a scope exclusion. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100% with a single required subscription_id, so the baseline is 3. The description goes further by telling the agent the value must come from list-webhook-subscriptions, which is actionable sourcing guidance the schema does not provide.

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 ('remove'/deletes) plus the exact resource ('webhook subscription') and the operational effect ('stop sending events to an endpoint'). This clearly separates it from the siblings create-webhook-subscription, update-webhook-subscription, and list-webhook-subscriptions without needing the schema.

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

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

'Use this when the user wants to remove a webhook subscription or stop sending events to an endpoint' gives explicit triggering conditions, and 'webhook test dispatch is not exposed' rules out a nearby use case. It stops short of naming update-webhook-subscription as the alternative for merely pausing/disabling, so it is not a full when-vs-alternative statement.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds rich operational detail beyond them: it specifies the external-provider state change, attempts webhook removal after authorization, and the effect of stopping provider events from reaching Autopilot. It also lists Enterprise access and manageable Space permission as prerequisites, which is exactly the kind of behavioral context an agent 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?

Two sentences with zero waste; the usage trigger is front-loaded, followed by the side effects and prerequisites. Every clause earns its place and no information is repeated unnecessarily.

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 mutation with no output schema, the description covers purpose, trigger conditions, destructive side effects, authorization requirements, and access prerequisites. An agent has enough to decide when and how to call it, and no return-value explanation is needed since no output schema exists.

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 schema itself documents both parameters with useful notes (e.g., 'Use list-space-repository-links first when needed' for link_id). The description merely restates that space_id and link_id are required, adding no meaning beyond what the schema already provides. Baseline 3 is appropriate when the schema carries the semantic load.

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

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

States a specific verb (disable) and resource (Autopilot repository link for a Space), and the phrasing 'pause, turn off, or disable' signals a reversible action that contrasts with permanent deletion. It does not explicitly name the sibling delete-space-repository-link, so an agent must infer the distinction from the name rather than being routed to the 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?

Provides clear when-to-use context ('Use this when the user wants to pause, turn off, or disable...'), which covers the common trigger. It does not explicitly state when not to use this tool or name the alternative (delete-space-repository-link for permanent removal), so an agent has no direct exclusion guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds useful context by stating this is a 'Destructive state-changing action' that 'marks the pending suggestion discarded directly after authorization.' It does not discuss reversibility or failure behavior, but it meaningfully supplements 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 sentences with no wasted wording. The use case is front-loaded, and the destructive nature and prerequisite are both stated compactly.

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

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

For a one-parameter destructive tool with complete schema coverage, no output schema, and annotations that already cover safety, the description supplies the essential context: what it does, when to use it, and where the ID comes from. It could be slightly richer about post-discard state or whether the action is reversible, but it is largely 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%, and the single parameter already documents that suggestion_id is the numeric Autopilot suggestion ID and that list-space-suggestions should be used first. The description repeats that source but adds no new syntax, validation, or constraint beyond the schema, 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 uses the specific verb 'discard' with the resource 'suggestion', scoped to one Autopilot/repository-sync documentation suggestion. It also gives multiple user-intent synonyms (reject, dismiss, remove from review), so an agent can distinguish it from apply-space-suggestion and snooze-space-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?

It clearly states when to use the tool and names the prerequisite source for the required ID: 'Requires suggestion_id from list-space-suggestions.' It does not explicitly exclude alternatives such as apply-space-suggestion or snooze-space-suggestion, so it falls short of full when/when-not guidance.

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

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

Beyond the annotations, it discloses the real side effects: the action enables the link and registers the provider webhook after authorization, calls out that it is state-changing and external-provider facing, and lists prerequisites (Enterprise access, manageable Space permission, provider access). This is exactly the extra context annotations cannot carry.

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

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

Two dense sentences, front-loaded with the usage trigger followed by the behavioral and prerequisite details. No filler or repetition of the title.

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

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

With no output schema, the description carries the return-side burden, and it adequately conveys the observable effect (link enabled, webhook registered) plus all access preconditions. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (space_id, link_id) are already fully documented in the schema. The description only restates that these are required without adding format, range, or lookup guidance, so baseline 3 applies.

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

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

States a specific verb and resource ('turn on or resume an existing Autopilot repository sync link for a Space') and is clearly distinguishable from its sibling disable-space-repository-link. An agent can identify the operation without opening any schema.

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

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

'Use this when the user wants to turn on or resume an existing ... link' gives a clear trigger condition. It does not, however, name the disable counterpart as an exclusion or point at list-space-repository-links (that routing hint sits in the schema, not the description).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds real value beyond them: the output is *merged* Markdown and is *returned inline in the MCP response* rather than as a file/download, which materially changes how an agent should handle the result. It does not disclose size limits, truncation, or behavior on very large exports.

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

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

Three short sentences, front-loaded with the primary use case, then the read-only guarantee, then the exclusion. Every sentence carries distinct information and there is no padding.

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 correctly compensates by stating that output is merged Markdown returned in the response, and the read-only nature is covered twice (annotation plus prose). It leaves gaps around large-export limits, error cases for invalid item IDs, and whether item_ids must all belong to space_id.

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 (space_id, item_ids) are already documented and the baseline is 3. The description adds only mild extra meaning by clarifying that selectable items span pages, folders, and docs, which suggests heterogeneous item types in item_ids, but it adds no format, limit, or ordering guidance for the ID array.

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 ('Markdown export of selected Space pages, folders, or docs') plus the output channel, which is enough to distinguish it from read siblings like get-space-document. It stops short of naming any sibling tool explicitly, and the ambiguity with copy-space-item is only implicitly resolved by the 'returned in the MCP response' phrasing.

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

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

It gives a clear trigger ('when the user wants a Markdown export ... returned in the MCP response') and an explicit exclusion for PDF, ZIP, and download-only flows. The redirect points at a generic 'browser guidance' flow rather than a concrete sibling tool, so the routing instruction is directional but not fully actionable.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses that authorization is required first, that the action consumes AI credits, that it creates a generation, and that it writes a document into the given space_id. Credit consumption and the auth prerequisite are non-obvious side effects the agent needs before calling.

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 front-loaded: the first states the selection condition, the second the side effects. No filler and nothing buried.

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 9-parameter, state-changing tool with no output schema, the description covers the selection context and side effects well. It does not indicate what comes back (e.g., a generation identifier usable with get-generation or add-generation-to-space), which is a minor gap given no output schema exists.

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

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

Schema description coverage is 100%, so every one of the 9 parameters is already documented in the schema, including space_id's 'call list-spaces first' hint and path's folder-creation behavior. The description mentions only space_id and source files, adding no syntax or format detail beyond what the schema provides.

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

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

The description states a specific verb and resource ('generate documentation') plus the key scoping qualifier 'saved directly in an existing Space,' which implicitly separates it from the many generate-* siblings that only produce a generation. It does not explicitly name the alternative tools (e.g., generate-code-documentation vs. add-generation-to-space), so it falls short of full sibling differentiation.

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

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

'Use this when the user supplies source files and wants the generated documentation saved directly in an existing Space' gives a clear triggering condition and a scope qualifier. There is no explicit when-not guidance or named alternative, but the context for invoking it is unambiguous.

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

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

Goes well beyond the annotations: it discloses that the action requires authorization, is state-changing, consumes AI credits, creates a private Space, links the repository, and queues per-file jobs. Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the meaningful behavioral burden and does so richly.

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, zero filler, with the usage trigger front-loaded and the side effects and required inputs packed into the second. Every clause carries information an agent needs.

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

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

For a credit-consuming, state-changing tool with no output schema, the description covers the trigger, side effects, and required inputs adequately. It stops short of describing the return payload (e.g., a generation/Space identifier for follow-up calls), which would be the remaining useful detail.

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 property descriptions already explain repository_id, selected_files, language, space_name, and additional_instructions in detail. The description only restates that repository_id and selected_files are used, adding no syntax or meaning 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?

States a specific verb and outcome: build a new documentation Space from selected files in an imported repository. The 'selected files' and 'new Space' framing implicitly distinguishes it from full-tree or add-to-existing generators, but among the many sibling generate-* tools (generate-code-documentation, generate-and-add-documentation, generate-repository-documentation) no sibling is named, so an agent still has to infer which generator applies.

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

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

Opens with an explicit trigger: 'Use this when the user wants a new documentation Space built from selected files in an imported repository.' The 'new Space' vs. add-to-existing and 'selected files' vs. whole-repo scoping implicitly routes against alternatives, but no when-not condition or named sibling alternative is given.

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

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

With readOnlyHint=false already signaling mutation, the description adds real value beyond annotations: it states the action consumes AI credits, creates a generation, and requires authorization before returning commented code. It also flags the file-upload path via browser guidance. It stops short of explaining where the output lands (response vs. generation history).

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 usage trigger and followed by the behavioral note. Every sentence carries information; no padding or restatement of the 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 three-parameter generation tool with full schema coverage and no output schema, the description covers the trigger, the cost/auth implications, and the return. The only gap is not specifying how the commented code is surfaced, but that is minor.

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

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

Schema description coverage is 100%, so all three parameters (name, filename, source_code) are already documented in the schema. The description adds no parameter-level meaning, making the baseline 3 correct.

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 ('add inline comments, docblocks, docstrings, or code annotations'), which clearly separates it from the code-tests, code-optimization, and documentation generators. It does not explicitly name or contrast with the nearest sibling (generate-code-documentation), so it falls short of a 5.

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

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

It gives a clear trigger condition: 'Use this when the user supplies source code and asks to add inline comments...'. There are no exclusions or named alternatives, but the context for invocation is unambiguous.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write nature is known; the description adds genuinely new context: it consumes AI credits, creates a generation record, and requires authorization before returning documentation. It does not describe latency or failure behavior, but the cost/authorization disclosure is meaningful beyond annotations.

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

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

Three sentences, front-loaded with the trigger, followed by behavioral cost/side-effect facts. Efficient overall, though the trailing 'use browser guidance for local upload or repository/full-tree flows' is terse and slightly cryptic about where that guidance lives.

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 5-parameter generation tool with no output schema, the description covers the trigger, side effects, cost, and authorization requirement, plus a pointer for adjacent flows. It leaves the returned documentation's shape and history/retrieval flow implicit, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (name, files, output_language, documentation_type, additional_instructions). The description adds only that files are the unit of work; it offers no syntax or format guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('generate') and resource ('markdown documentation') and scopes the input to 'one or more files', which separates it from repository/full-tree siblings. It does not name those siblings explicitly, but the 'file-level' scope is 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?

Opens with a concrete trigger ('when the user supplies source code and asks to generate markdown documentation, explain code, or document one or more files') and routes repo/local-upload flows elsewhere via browser guidance. No explicit exclusion naming a sibling tool like generate-full-tree-documentation, so it stops short of 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses that authorization is required, that AI credits are consumed, that a generation is created as a persistent side effect, and that revised code is returned. It does not say whether the generation is produced synchronously or must be fetched later via get-generation, which is a meaningful gap given the surrounding generation-lifecycle siblings.

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, zero waste. The usage trigger is front-loaded and the behavioral facts are packed into the second sentence rather than spread across filler.

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

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

With no output schema, the description correctly names the return value ("returns the revised code"), and the side effect plus credit cost are stated. It leaves open the async/polling question and any reversibility of the created generation, which an agent may need given archive-generation and get-generation siblings.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including optimization_focus and additional_instructions. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

The description states a specific trigger and outcome: source code in, optimized/refactored code out. That distinguishes it from siblings like generate-code-comments, generate-code-tests, and generate-language-conversion, though it never names a sibling explicitly.

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

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

"Use this when the user supplies source code and asks for an optimized or refactored version" gives a clear use condition. It does not state when NOT to use it or which sibling to prefer for overlapping requests (e.g., language conversion), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's real contribution is the extra context it adds: the action consumes AI credits, creates a persistent generation record, and returns test code only after authorization. That is meaningful beyond the structured fields; only rate/credit limits or failure modes are missing.

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 padding. The trigger condition is front-loaded, the cost/authorization caveat follows, and the routing exclusion closes it out.

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, and the description partially compensates by saying test code is returned after authorization. Combined with annotations and full schema coverage, an agent has enough to invoke correctly; only the shape/format of the returned test code is left implicit.

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

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

Schema description coverage is 100%, so all six parameters (filename path format, framework, auto-detect, additional instructions) are already documented in the schema. The description adds only the mention of test kinds, which does not extend parameter meaning. Baseline 3 applies.

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

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

States a specific verb (generate) and resource (tests) and enumerates the supported test kinds: unit, feature, integration, framework-specific. This clearly separates it from the many generate-* documentation siblings, and an agent can classify a request without opening the schema.

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

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

Explicit trigger is given ("Use this when the user supplies source code and asks to generate ... tests"), plus an exclusion routing to browser guidance for local uploads or repository-wide generation. The alternative is described generically rather than by a concrete sibling tool name, which keeps it short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description discloses several consequential traits: it is state-changing, consumes AI credits, creates a private linked Space, requires prior authorization, and queues work asynchronously from stored preview data rather than from live input.

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

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

Two tight sentences: the first front-loads the trigger condition, the second enumerates cost, side effects, and the identifying parameters. No filler or restatement of the title.

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

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

For a mutation tool with no output schema, it covers prerequisites, authorization, cost, side effects, and the identity of the queued job. It leaves open what happens after queueing (e.g., how completion is observed, or behavior on a stale hash), which the schema's hash-mismatch note only partially addresses.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by tying repository_id and accepted_tree_hash to the stored preview and the 'exact approved preview' condition. It does not add format-level detail beyond the schema for the optional parameters (space_name, excluded_paths).

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

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

The description states a specific verb and resource ('create its documentation Space' from a stored full-tree preview) and pins the triggering precondition (user reviewed a full-tree preview). It clearly separates this from the sibling preview tool and from one-shot generators like generate-repository-documentation, though it does not name those alternatives explicitly.

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

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

It gives a clear triggering condition ('Use this when the user has reviewed a full-tree preview and asks to create its documentation Space') and an 'After authorization' gate. There is no explicit when-not guidance or named alternative for cases where no preview exists, so it falls short of a 5.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantial context beyond them: authorization is required, AI credits are consumed, the action is state-changing, and saved results in public Spaces become publicly visible. That public-exposure warning is a genuinely useful risk disclosure missing from structured fields, though rate limits or failure behavior aren't 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?

Three sentences, front-loaded with the usage trigger, then behavior, then return/side effects. Dense and mostly waste-free, though the third sentence packs several distinct facts and could be split for clarity.

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

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

With no output schema and seven parameters, the description carries return-value burden and does address it ('returns converted code') along with the optional save path and its exposure implications. Enough for an agent to call it correctly, though it doesn't describe the generation object or error cases.

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

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

Schema coverage is 100%, so baseline is 3; the description goes slightly beyond by tying the inputs together as a generation source and flagging that save_to_space carries a manage-permission requirement and public-visibility consequence, which is meaning the schema alone doesn't convey.

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

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

The description names a specific verb and resource ('converts one source-code file to another programming language or framework') and scopes it to a single file, which distinguishes it from the repository- and codebase-level generation siblings like generate-repository-readme or generate-code-optimization.

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

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

'Use this when the user supplies one source-code file for conversion' gives a clear triggering condition, and the schema's source_code description further routes local file uploads elsewhere. It does not explicitly name a sibling alternative or an exclusion case, so it falls short of a 5.

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

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

Goes well beyond the annotations by disclosing that this is state-changing, requires authorization, consumes AI credits, and that optional Space saving 'may make the output publicly accessible' — a meaningful side-effect warning. This is consistent with readOnlyHint=false and adds genuine behavioral context the annotations cannot convey.

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

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

Two sentences, front-loaded with the 'Use this when...' trigger, with no filler. Slightly dense in the second sentence but every clause (auth, credits, repo_id/selected_files, Space saving public exposure) 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 mutation tool with six parameters (including a nested object) and no output schema, the description covers authorization, credit cost, side effects, and the public-accessibility caveat. It lacks any note on return/result format, but absent an output schema this omission is minor.

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

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

Schema description coverage is 100%, so all six parameters (including the nested save_to_space object) are already documented in the schema, including the 'numeric repository_id, not a slug/URL' constraint. The description reinforces 'numeric repository_id and selected_files' and the public-access risk of Space saving, but adds little beyond what the schema already provides. Baseline 3 applies.

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

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

States a specific verb (generate) and resource (one markdown document from selected files in an imported repository), which is concretely scoped. It implicitly distinguishes itself from full-tree/codebase siblings via 'from selected files,' but never names or contrasts an alternative, so it falls short of the sibling-differentiation needed for a 5.

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

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

The opening 'Use this when the user wants one markdown document generated from selected files in an imported repository' gives explicit, actionable usage context. However, in a crowded space of generate-* siblings (codebase, full-tree, readme, release-notes), it offers no exclusions or guidance on when to pick a different generator.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description adds substantial context beyond that — that it is a state-changing action, consumes AI credits, creates a generation, requires prior authorization, and can publish to a Space where it may be publicly accessible. These are exactly the side effects an agent needs to warn a user about.

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

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

A single dense sentence, front-loaded with the trigger and followed by prerequisites and side effects. Every clause carries information, though the packed semicolon structure is slightly heavy 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?

No output schema exists, and the description covers the authorization requirement, credit consumption, generation creation, and the public-visibility risk of save_to_space — the key facts an agent needs before invoking a mutation tool.

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

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

Schema description coverage is 100%, so the parameter burden is already carried by the structured fields; the description's note that repository_id must be numeric and not a slug/URL/provider name is a restatement of the schema's own description. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource: generate or refresh a README for an imported repository. It is clear what the tool produces, but among the many generate-* siblings (generate-repository-documentation, generate-repository-release-notes, generate-and-add-documentation) it never names which artifact distinguishes it beyond the word README.

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

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

Gives an explicit trigger: 'Use this when the user asks to generate or refresh a README for an imported repository.' That is a clear context for invocation, but there are no exclusions or pointers to alternatives for overlapping documentation-generation tools.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, so the mutation/open-world profile is partly covered. The description adds real value beyond that: it requires prior authorization, consumes AI credits, creates a generation, and can optionally save to a Space — cost and side-effect context an agent cannot get from 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?

Two tightly written sentences: the first front-loads the trigger, the second enumerates the behavioral chain (auth → compare → credit cost → generation → optional save). No filler, no repetition of the 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?

With 100% schema coverage, annotations, and no output schema, the definition covers trigger, authorization, cost, and side effects adequately for a 7-param nested tool. It omits what the resulting generation contains or how it is later retrieved (e.g., get-generation), a minor gap given no output schema exists.

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 7 parameters including the nested save_to_space object. The description only names base_branch and compare_branch as the comparison pair, adding no format or constraint detail 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?

Names a specific verb (generate) and resource (repository release notes) and scopes it precisely: release notes from two branches of a connected provider repo. This clearly distinguishes it from the many sibling generate-* tools (generate-repository-documentation, generate-repository-readme, generate-code-comments).

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

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

"Use this when the user wants release notes from two branches of a connected provider repository" gives a clear triggering condition. It stops short of naming alternatives or stating when-not to use it (e.g., versus generate-repository-documentation or generate-repository-readme), so it is not fully explicit routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds meaningful context beyond these: it consumes AI credits, creates a generation, requires authorization, and warns that saved results in a Space may be publicly accessible. That is substantive disclosure, though it doesn't cover reversibility or rate limits.

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

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

Two sentences, with the usage condition front-loaded before the behavioral/payload details. Dense but wastes little; the only mild looseness is packing the input-path and Space caveats into the second clause.

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

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

With no output schema, the description correctly states the return (OpenAPI JSON) and notes auth, credit consumption, and public Space exposure. Given full schema coverage and nested objects, this is essentially complete, though save_to_space semantics and the parent_id option aren't clarified.

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 fully documents all 6 parameters (including the nested files[] path). The description notes the single-file vs. multiple-files paths and the Space-save option, but this largely restates what the schema already explains, so baseline 3 applies.

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

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

The description states a specific verb (generate), resource (OpenAPI/Swagger specification), and input (API source code). It clearly distinguishes itself from siblings like generate-code-documentation or generate-repository-documentation by naming the exact output type, so an agent can select it without opening the schema.

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

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

The opening sentence gives an explicit trigger condition: use when the user supplies API source code and asks for an OpenAPI/Swagger spec. It clarifies usage context well but does not name a sibling alternative or state when NOT to use this tool, so it falls short of a full 5.

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

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

Beyond annotations, the description discloses critical behavioral traits: it is state-changing, consumes AI credits, creates a generation, can save markdown to a Space, and notes that public Spaces expose saved diagrams. It also mentions authorization is required.

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?

Four sentences, front-loaded with the primary use case, then behavioral context, then save behavior, then alternative guidance. Every sentence contributes necessary information 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?

The description covers purpose, usage, side effects, cost, and save behavior well. However, it does not mention what the tool returns (e.g., a generation ID or URL) which would help an agent know how to access the result, given the absence of an output schema.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces the diagram types but adds no new parameter-level meaning beyond what the schema provides.

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

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

The description specifies the verb 'generate' and the resource 'UML diagram', and lists supported diagram types (UML, Mermaid, sequence, class, component, architecture). This clearly distinguishes it from sibling generate-* tools that produce documentation, tests, or comments.

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: 'when the user supplies source code and asks for UML... diagrams.' It also provides a when-not/alternative: 'Use browser guidance for local uploads or full-repository diagrams,' covering edge cases where this tool is not appropriate.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description still adds real value beyond them by disclosing what is returned ('effective personal/team preferences') and that editability is reported without mutating settings.

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, zero waste, with the trigger condition front-loaded ahead of the read-only/return behavior. Every clause earns its place.

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

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

For a zero-parameter read with no output schema, the description adequately covers both when to call it and what comes back, including the personal-vs-team resolution and editability flag. It could go slightly further on return shape, but nothing essential to invoking it correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The description does not need to compensate for any schema gap here.

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 ('view') and resource ('AI writing guidelines, templates, strict mode, generator scope, team-enforced generation preferences'), enumerating exactly what is returned. The read-only framing implicitly separates it from the sibling update-ai-preferences, so an agent can route correctly without opening either schema.

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

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

'Use this when the user wants to view...' gives a clear, explicit trigger condition tied to user intent. It stops short of naming update-ai-preferences as the mutation alternative or stating when-not to use it, so it is strong context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description still adds useful behavior — that it performs no provider polling, starts no work, and that state-changing steps are browser-only. It stops short of describing the returned status payload or how long runs may take to appear.

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, zero padding: trigger first, read-only/no-side-effect guarantee second, scope exclusions third. Every clause carries information an agent would otherwise have to guess.

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 must convey what a caller receives; it says only 'returns the latest run or a specific run_id' without describing the status/progress fields or what a not-yet-started run looks like. Input side is fully covered, so the gap is on the return-value side only.

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, including run_id being optional and space_id requiring list-spaces resolution. The description reinforces run_id's meaning ('latest run or a specific run_id') but adds no format, range, or ownership details beyond the schema. Baseline 3 applies.

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

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

The description states a specific verb and resource — retrieving progress or results of a documentation update review in an existing Space — and explicitly bounds what it is not ('without polling providers or starting work'). An agent can separate it from start-documentation-update and inspect-documentation-update without opening the schema.

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

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

It gives a concrete trigger ('Use this when the user wants progress or results') and rules out adjacent flows ('Change decisions, resume and end remain browser flows'). It does not name the closest sibling tools (start-documentation-update, inspect-documentation-update) by name, so the routing is inferred rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description nonetheless adds substantive behavioral context by enumerating the return payload, including a credit impact figure and an acceptance hash — non-obvious details an agent would otherwise not anticipate. It does not contradict the annotations.

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

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

Two sentences: the first front-loads the trigger condition, the second lists the return surface. No filler or restated title. It could be tightened slightly by naming the sibling tool, but 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?

There is no output schema, so the description compensates well by enumerating the returned fields. For a one-parameter read tool with full annotation coverage, the only real gap is the absent pointer to the generate-* counterpart for the pre-preview state.

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% for the single repository_id parameter, and the schema itself already warns against passing a Space ID, slug, provider URL, or repository-link ID. The description reinforces 'numeric repository_id' and ties the acceptance hash to it, but adds little beyond what the schema states, so the baseline 3 applies.

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

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

The description names a specific verb/resource pairing — inspecting an existing full-tree documentation preview — and enumerates exactly what it returns (repository details, tree titles, page counts, source-file counts, credit impact, acceptance hash). It is clearly a read counterpart to generate-full-tree-documentation, but it never names that sibling, so the differentiation is inferable rather than explicit.

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

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

The opening clause gives a concrete trigger: 'when the user wants to inspect an existing full-tree documentation preview before creating a Space.' That is a real usage condition tied to a workflow step. However, it stops short of naming the alternative (generate-full-tree-documentation) or stating what to do if no preview exists yet.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the description's 'Read-only... without changing it' largely restates structured data. It adds only the fact that lookup is by numeric generation_id, which is already implied by 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?

A single front-loaded sentence pairs the trigger condition with the safety note; nothing is wasted. It is slightly list-dense but appropriately sized for a two-parameter read tool.

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

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

For a simple read-only single-record fetch with fully documented params and no output schema, the description covers when to use it and what it returns (markdown, version metadata). Missing pagination/return-structure notes are minor at this complexity.

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

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

Schema description coverage is 100%, so both generation_id and include_source are already documented in the schema, including the 'Call list-generations first' prerequisite. The description adds no parameter-level detail beyond that, making 3 the correct 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?

States a specific verb (read) plus concrete resources (generated output/result, version metadata, generated markdown), which is materially more informative than the name alone. It does not explicitly contrast itself with the closest siblings (list-generations, update-generation), so it stops short of a 5.

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

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

The opening 'Use this when the user wants to...' gives clear trigger conditions, including the distinct case of picking a version for later actions. It never names an alternative tool or an exclusion, so it stays below the explicit when/when-not bar of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds non-obvious context on top: it is an Enterprise-gated feature, results are ordered newest first, and access is required. It still doesn't disclose pagination/truncation behavior at the 500-entry cap, which is the one behavioral gap.

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

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

Two sentences, no filler: the first is a usage trigger, the second packs the read-only guarantee, ordering, and prerequisites. Front-loaded with the decision-relevant information.

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

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

For a 3-param read tool with no output schema, the description covers purpose, trigger conditions, ordering, and the Enterprise gate; the safety profile is carried by annotations. Only the return shape and cap behavior are left implicit, 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% – limit, since, and space_id are all documented in the schema, including the 'call list-spaces first' hint. The description only restates that space_id must be numeric and Enterprise-gated, adding no syntax or format meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('returns the Space activity/audit log') plus its ordering ('newest first'), which cleanly separates it from neighbors like list-webhook-logs and get-space-document. An agent can identify the tool from the description alone.

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 names the triggering user intents: 'what changed in a Space, who changed settings, sync events, document actions, or recent activity.' It also states the Enterprise prerequisite. It does not name an alternative tool or a when-not condition, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'read-only, does not change content' sentence is partly redundant. However, the description adds real value by naming the return payload ('full markdown content') and the upstream prerequisite chain for the document ID. It does not discuss size limits or pagination for large documents.

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

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

Two tight sentences with zero filler, and the use case is front-loaded before the prerequisite. Every clause carries information.

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

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

For a two-parameter read tool with no output schema and full annotation coverage, the definition covers trigger, safety, return content type, and prerequisites. The only gap is behavior for very large documents or missing/invalid IDs.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema (including the space_id note to call list-spaces first). The description adds only provenance for document_id, and never mentions space_id at all, so it does not exceed the schema 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?

States a specific verb and resource: read the full markdown content of a specific Space document/page. It also distinguishes itself from the discovery siblings (list-space-documents, search-space-documents, global-search), which only locate documents rather than returning 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?

Explicitly states the triggering condition ('after search or listing') and names the three tools that supply the required document ID. An agent knows exactly when to reach for this tool and what must happen before it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description reinforces this ('Read-only... without changing account data'). More valuably, with no output schema it discloses the return shape (account name plus can_generate boolean), which the agent could not otherwise know.

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

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

Two tight sentences: the first front-loads the usage trigger, the second states the behavior and return. Every clause earns its place with no filler.

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

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

For a zero-param, read-only tool with no output schema and rich annotations, the description covers the essential usage trigger and the return fields. It is complete enough to call correctly, though it could note there is no pagination or filtering to worry about.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is required and adds nothing misleading about arguments.

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 outcome: it returns the account name and a can_generate boolean, which bridges the mismatch between the tool name (get-user-info) and its title (Get Account Generation Status). It is clear what the tool does, though it does not explicitly differentiate itself from look-alike siblings like list-generators or 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?

It gives explicit trigger conditions: 'Use this when the user asks which DocuWriter.ai account is connected or whether it can run a generator.' That is a concrete when-to-use, but it names no alternatives or exclusions, so the routing is clear without being fully disambiguated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is largely covered. The description adds useful context by specifying what is returned (matching titles, snippets, Space details, URLs), which matters because there is no output schema. It does not contradict annotations.

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

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

Two sentences, front-loaded with the usage condition, followed by the read-only guarantee and return contents. Every sentence earns its place with no redundancy.

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

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

For a simple two-parameter search tool with annotations covering safety and no output schema, the description is largely complete: it explains scope, read-only behavior, and return fields. It does not discuss pagination or result limits, but the schema covers per_page, so 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% for both parameters (query, per_page), so the schema already documents required input and limits. The description adds no syntax, format, or constraint details beyond what the schema provides, making the baseline 3 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 (search) and resource (documents across every accessible Space), and explicitly contrasts its scope with searching 'one known Space,' which distinguishes it from the sibling search-space-documents tool. It also names the return contents (titles, snippets, Space details, URLs).

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 when-to-use condition ('when the user wants to search documents across every accessible Space') and an implicit when-not ('rather than one known Space'). However, it does not name the alternative tool (search-space-documents) explicitly, leaving the agent to infer which sibling to use for a single Space.

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

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

Annotations already establish read-only, non-destructive, open-world behavior. The description adds useful context by naming the returned readiness, credit impact, and review_quote fields, and by clarifying that no review is started and follow-up actions remain browser-based.

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 tight sentences with the usage trigger front-loaded and no redundant restatement of the name or title. Every sentence contributes either selection guidance, behavioral boundaries, or return-value 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 two-parameter read-only inspection tool with no output schema, the description names the key return values and clarifies what the tool does not do. The exact structure of readiness and credit impact is not detailed, but the schema covers the inputs and annotations cover safety.

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 reinforces that selected pages are optional and ties them to review_quote, but it adds no syntax or format detail 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 states a specific verb and resource: inspect an existing Space for repository documentation updates. It distinguishes itself from start-documentation-update by explicitly saying it starts no review, but it does not clarify how it differs from the sibling get-documentation-update-status.

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 usage condition: use when the user wants to check an existing Space for repository documentation updates. It also sets boundaries by saying change decisions, resume, and end remain browser flows, though it does not name the closest sibling alternative for status checks.

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

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

Beyond the annotations, the description discloses that this is a state-changing external action, that it occurs after authorization, that it creates a pending invitation, that exactly one email is sent, and that acceptance happens in the browser. These are valuable behavioral details for an agent invoking a mutation tool.

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-loads the usage condition, and moves directly into important behavioral context. Every sentence contributes 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 two-parameter mutation tool with annotations and no output schema, the description covers the trigger, side effects, authorization context, and invitation acceptance flow. An agent has enough information to invoke it 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 description coverage is 100%, so both parameters are already well documented in the schema. The description reinforces the email and role inputs but does not add syntax, format, or constraints beyond what the schema provides; 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: invite a teammate by email with an editor or viewer role. The intended action is clear and distinguishable from most siblings, but it does not explicitly contrast with related tools like cancel-team-invitation 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?

It gives a clear triggering condition: use when the user wants to invite a teammate by email with an editor or viewer role. It does not list exclusions or explicitly name alternative tools to use instead, but the context is sufficient for correct selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; the description's 'without changing anything' largely restates it. Genuine additions are the visibility scope (personal/team generations) and the archived-items note, but preview-vs-full-content merely mirrors the include_content parameter.

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

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

Two sentences, with the use-case triggers front-loaded and the read-only constraint second. No filler, though the second sentence spends words on read-only behavior the annotations already declare.

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 no output schema, the description plus full schema coverage give an agent enough to call it correctly: triggers, scope of visibility, and archive/preview options. It is slightly thin on how results are paged and what the listing returns, but the parameters carry that load.

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

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

Schema description coverage is 100%, so all five optional parameters (page, type, archived, per_page, include_content) are already documented in the schema. The description adds no format, enum, or pagination detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource (lists generations) and scopes it to visible personal/team generations, so an agent can distinguish it from write siblings like archive-generation or restore-generation. It stops short of explicitly contrasting with the two closest siblings, get-generation (single item) and list-generators (generators rather than outputs).

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

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

The opening clause gives concrete triggers — find generated outputs, generation history, previous results, archived items, IDs for later generation actions — which is clear contextual guidance. It never states when to prefer get-generation or list-generators instead, so it stops at clear context rather than full alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it enumerates what is returned (identifiers, required inputs, credit behavior, Space output behavior, browser-only boundaries) and confirms nothing is executed.

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, zero waste. The usage trigger is front-loaded and the read-only return summary follows, so the agent gets the essential facts in reading order.

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, so the description must describe the return payload, and it does so by listing the categories of information returned. That is enough to call the tool correctly; only the exact response shape/format is left unspecified, a minor gap for a parameterless read 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 tool takes zero parameters, so there is nothing for the description to clarify beyond the empty schema. Baseline 4 applies; no parameter-level detail is expected or 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?

States a specific verb and resource ('list' generators) and immediately scopes it against the many generate-* siblings with 'without running a generator.' An agent can distinguish this discovery tool from the generation tools without opening any schema.

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

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

Gives a clear trigger ('when the user asks which generators are available or what inputs a generator requires') and an implicit exclusion (it does not run a generator). It stops short of naming a specific alternative tool for the opposite case, so it is strong context rather than full routing guidance.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds meaningful context beyond that: it returns provider status plus browser-only connect/reconnect guidance, and explicitly notes that credentials are not exposed.

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 waste, front-loaded with the usage trigger before the behavioral and disambiguation notes. Every clause earns its place.

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

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

For a read-only, zero-required-parameter listing tool with a fully documented schema and existing annotations, nothing needed to invoke it correctly is missing; no output schema exists, so return-value explanation is unnecessary.

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 both the provider filter and include_guidance. The description echoes the browser-only guidance concept but adds no syntax or default details beyond what the schema supplies, making the baseline 3 appropriate.

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

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

States a specific verb+resource (list provider connections) and enumerates the exact providers covered (GitHub, GitLab, Bitbucket, Azure DevOps), so an agent immediately knows what is being enumerated. It also distinguishes itself from the repository-link tools, avoiding confusion with list-space-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?

Gives concrete trigger conditions ('when the user asks whether X is connected') and names an alternative ('Use repository-link tools for Space Autopilot links'). It does not, however, clearly distinguish itself from the closest sibling list-provider-repositories, which also concerns imported repositories.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing that the call may return reauthorization/browser guidance rather than data — an out-of-band outcome an agent otherwise would not expect. It stops short of describing pagination 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?

Three short sentences, front-loaded with the trigger condition, then the read-only framing, then prerequisites. Dense but every clause carries information; nothing is padding.

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 compensates by telling the agent what comes back (repository choices or reauthorization/browser guidance). Combined with full parameter coverage and read-only annotations, an agent has enough to call this correctly; only pagination/emptiness behavior is unaddressed.

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 both parameters are fully documented in the schema, so the baseline of 3 applies. The description only restates that provider and space_id are required, adding no format or constraint detail beyond the schema's own enum listing.

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 ('fetches repository choices') scoped to connected external providers, and situates it in the Autopilot setup flow. It implicitly distinguishes itself from list-provider-connections and list-space-repository-links, though it never names those siblings to sharpen the contrast.

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

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

'Use this when the user wants to choose a repository from a connected provider before creating an Autopilot link' gives a concrete triggering condition. There is no explicit when-not or named alternative, so the agent must infer that existing links are handled elsewhere.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description reinforces this ('Read-only... without changing content') and clarifies the scope is one space, but adds little beyond what annotations provide and says nothing about pagination or result volume.

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

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

Two tight sentences, front-loaded with the 'Use this when...' trigger clause and followed by the read-only scoping caveat. No filler, though the read-only statement is mildly redundant with 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 one-parameter, read-only listing tool with no output schema, the description covers trigger, scope, and side-effect profile adequately. The only gap is the absence of routing guidance against search-space-documents, which would help an agent choose 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% and the single parameter is already documented, including the 'Call list-spaces first' prerequisite. The description only restates that it is one numeric space_id, adding no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

The description gives a specific verb ('list/browse') and resource ('documents and folders in a Space tree'), and scopes it to a single numeric space_id. It does not name the closest siblings (search-space-documents, get-space-document) to sharpen the boundary, but the intent is 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 states clear trigger conditions: browsing a Space tree, listing pages/docs/folders, finding numeric IDs, or inspecting structure before editing. It stops short of naming alternatives (e.g. use search-space-documents for keyword lookup) or stating when not to use it, so it falls short of a 5.

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

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

Annotations already declare read-only, non-destructive, and closed-world behavior. The description reinforces this and adds useful context that activity is bounded and raw provider payloads are not exposed, though it does not discuss permissions or detailed response shape.

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 focused sentences with no wasted text. The usage condition is front-loaded and the read-only return behavior follows immediately.

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 read-only annotations and fully described schema, the description is nearly complete. It explains what is returned at a high level and notes the bounded activity/raw-payload constraint, though it could say more about link fields or response structure since no output schema exists.

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 space_id, activity_limit, and include_activity thoroughly. The description adds a little context about bounded sync activity, but parameter meaning is primarily carried by the schema, making 3 the appropriate 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 and resource: listing repository links for a Space. It also frames the purpose around Autopilot, repo sync, suggestion generation, trigger events, and sync activity, though it does not explicitly contrast itself with sibling tools like update-space-repository-link or delete-space-repository-link.

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

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

It gives clear when-to-use scenarios: when the user asks which repositories are linked to a Space for Autopilot, repo sync, suggestions, triggers, or recent activity. It stops short of naming exclusions or alternatives, but the intended context is explicit.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, and the description largely restates them ('read-only... does not change settings or documents'). It adds one genuinely new fact — the returned set is limited to 'accessible' Spaces — but says nothing about ordering, format, or limits.

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 filler, with the primary use case front-loaded and the read-only caveat second. Every clause earns its place.

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

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

For a parameterless read-only lookup with no output schema, the description covers purpose, trigger, and the key behavioral fact (accessible Spaces). Slightly incomplete in that it does not hint at what each Space entry contains, but nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to convey; baseline is 4. The description does not introduce phantom parameters, which is correct.

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 (list/look up) and resource (documentation Spaces), and distinguishes itself from siblings like list-space-documents by scoping to Spaces themselves. An agent can tell this apart from the many 'list-space-*' tools without opening a schema.

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

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

Explicit trigger: 'when the user asks to see, choose, or look up their documentation Spaces,' plus a sequencing hint about needing a numeric space_id first. No when-not guidance or named alternative, but the context is clear enough to route correctly.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, and the description reinforces this while adding real value beyond them: it states that the return is 'suggestion inbox items and IDs for later apply/discard/snooze tools without changing documents.' That tells the agent what it gets and that it is a safe, non-mutating read, which is more than the annotations convey.

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

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

Two tight sentences, front-loaded with the usage condition and followed by the behavioral note. Nothing is wasted, though the status enumeration is slightly overlong for the value it adds.

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

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

With no output schema, the description correctly steps in to say it returns inbox items and IDs, which is what an agent needs to chain into apply/discard/snooze. Pagination/limit behavior is left to the schema, which is fine since it is documented there.

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 limit, status, batch_id, and space_id (including the 'call list-spaces first' hint). The description adds no parameter-level detail and its status examples actually conflict with the schema enum, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('list ... documentation suggestions for a Space') and distinguishes itself from mutation siblings like apply/discard/snooze by framing it as a review operation. The status list ('pending, snoozed, done, high-confidence') does not match the schema's accepted values (pending, applied, discarded), which slightly muddies what it actually returns.

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

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

'Use this when the user wants to review ... suggestions' gives a clear triggering context, and it explicitly positions itself as the read step preceding apply/discard/snooze. It never names count-space-suggestions or bulk-manage-space-suggestions as alternatives, so the routing is helpful but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'read-only ... without changing state' clause adds little new. The valuable addition is the disclosure of return content (roster, pending invitations, roles, capabilities, invitation-acceptance guidance), which is useful context since no output schema 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?

Two sentences, front-loaded with the 'Use this when...' trigger ahead of the read-only/return detail, and every clause maps to a concrete use case. The long enumeration is slightly list-heavy but nothing is wasted.

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

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

For a simple, zero-parameter read tool with no output schema, the description covers usage triggers, the read-only safety posture, and what gets returned. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify beyond confirming it requires no input. Baseline 4 applies for a parameterless tool.

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

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

States a specific verb+resource (list team members) and enumerates the exact scope it covers: current roster, pending invitations, available roles, and capabilities. Read-only framing cleanly separates it from the write siblings (invite-team-member, remove-team-member, update-team-member-role), so an agent can identify it without opening the schema.

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

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

Provides explicit trigger scenarios (user asks who is on their team, which seats exist, what roles are available, whether pending invitations exist), which is stronger than implied usage. However, it names no alternative tool and gives no when-not-to-use guidance, so it falls short of the 5 bar.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; the description reinforces this and adds that it returns event keys and labels without altering subscriptions. This extra return-content context is useful beyond the annotations, though the read-only claim partly restates the hint.

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, zero waste, front-loaded with the triggering user intent followed by the read-only guarantee. Nothing is padded or repeated unnecessarily.

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 enumeration tool with no output schema, the description supplies both the trigger condition and the shape of the result (event keys and labels). Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the schema is trivially complete. Baseline for a no-parameter tool 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?

States a specific verb and resource: it lists the available webhook events, event names, and callback triggers, returning supported event keys and labels. This is clearly distinguishable from list-webhook-subscriptions and list-webhook-logs, which enumerate different resources, so an agent can select it 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?

Gives explicit when-to-use context: 'when the user asks what webhook events... are available before creating or editing a webhook subscription,' which anchors it relative to the create/update subscription siblings. It does not explicitly name an alternative or a when-not-to-use case, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is covered; the description reinforces read-only and adds two useful facts not in the annotations: results are bounded and limited to subscriptions the caller owns (an authorization/scope constraint). It stops short of describing ordering or pagination behavior beyond the bound.

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

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

Three tight sentences with no filler, front-loading the usage trigger before the behavioral and prerequisite notes. Every clause carries information an agent needs to select and call the tool.

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

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

For a read-only list tool with a fully documented schema, the description covers when to use it, its scope, and the shape of the return ('delivery log summaries'). With no output schema, a sentence on ordering or how logs are identified would round it out, but 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?

Schema description coverage is 100% and all four filters (limit, success, event_type, subscription_id) are documented in the schema itself. The description adds no syntax, format, or filtering semantics beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (webhook delivery logs), with scope qualifiers ('bounded delivery log summaries for owned subscriptions') that let an agent separate it from list-webhook-subscriptions. It does not, however, distinguish itself from the sibling list-webhook-events, and the phrase 'payload event logs' arguably overlaps that tool's territory.

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

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

Opens with a concrete trigger phrased in user intent ('when the user asks whether webhooks delivered, failed, retried'), which maps directly onto the success/failure/retry semantics of the tool. It also names the prerequisite alternative explicitly: use list-webhook-subscriptions first when a subscription ID is needed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description reinforces this and adds scope ('owned' subscriptions) and the no-mutation guarantee. It stops short of describing return shape or count/pagination behavior, which for a list tool with no output schema would have been useful, but with annotations carrying safety this is solid.

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

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

Three short sentences, front-loaded with the trigger condition, then the read-only guarantee, then the sibling redirect. Every sentence adds distinct value with no 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 parameterless read-only list tool with no output schema, the description covers purpose, trigger, and the nearest alternative tool. The only missing piece is any hint about the returned collection (size, pagination, fields), which is a minor gap given the absence of an output schema.

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

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

Zero parameters, so the baseline is 4. There is nothing for the description to disambiguate and it makes no misleading claims about inputs; it simply omits any mention of parameterization, which is appropriate for a no-arg listing call.

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

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

States a specific verb+resource (list webhook subscriptions) and anticipates the user's vocabulary with concrete synonyms (callback URLs, integration subscriptions, event endpoints). It differentiates from the closely named sibling by pointing to list-webhook-events for event keys, so an agent can pick it apart from the other 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?

Opens with an explicit trigger ('Use this when the user asks which webhooks... are configured') and names the alternative tool (list-webhook-events) for the distinct job of discovering valid event keys. Nothing is left to inference for when 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.