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

Annotations already declare idempotentHint=true, but the description supplies the concrete mechanism ('Adding a URL that is already on the list leaves the list unchanged') and discloses an auth requirement ('Requires the caller OAuth token') not present in structured data. It stops short of describing response shape or permission/scope specifics, so not a 5.

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

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

Four short sentences, each carrying distinct payload (purpose, two alternatives, auth requirement, idempotency behavior), with the core purpose front-loaded.

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

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

Only two required scalar parameters, no output schema, no nesting, and annotations cover the safety profile. Purpose, routing, auth, and idempotency are all present, so nothing needed 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 parameters (uri, environmentId) are already documented in the schema including the env_<id> pattern. The description adds no format or syntax detail 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?

States a specific verb and resource ('Add one URL that a user may be sent to after logout') and explicitly distinguishes itself from add_redirect_uri (login callback) and list_redirect_uris. An agent can select it correctly without reading 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?

Names two sibling alternatives and the exact condition that selects each ('Use add_redirect_uri for a login callback URL. Use list_redirect_uris to read the current list'). When-vs-when-else is fully resolved.

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 by disclosing an auth prerequisite ('Requires the caller OAuth token') and by giving concrete meaning to idempotentHint=true ('Adding a URL that is already on the list leaves the list unchanged'). It does not describe failure behavior for an invalid environmentId or whether the change propagates immediately, so it is strong but not exhaustive.

Agents need to know what a tool does to the 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 short sentences, each earning its place: purpose first, then the two sibling routes, then the auth requirement and idempotency note. No filler and the primary action is front-loaded.

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

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

For a two-parameter mutation with no output schema and annotations already covering the safety profile, the description supplies the remaining essentials: purpose, auth requirement, alternative tools, and idempotent semantics. 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% for both parameters, so the schema already explains 'uri' and 'environmentId' formats. The description adds no extra parameter syntax or constraints beyond what structured data provides, which is the expected baseline of 3 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 and resource ('Add one login callback URL to an environment') and immediately differentiates itself from the post-logout sibling. An agent can tell exactly which mutation this is versus add_post_logout_redirect_uri 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?

Explicitly routes the caller to alternatives with their selecting conditions: add_post_logout_redirect_uri for post-logout URLs and list_redirect_uris to read the current list. When-to-use and when-to-use-something-else are both covered, leaving nothing to inference.

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

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

Beyond the annotations (which only flag non-readOnly/non-idempotent/non-destructive), it adds an auth requirement ('Requires the caller OAuth token') and return semantics ('Each call returns a new link and an expiry'), reinforcing the non-idempotent behavior. It stops short of describing scopes or failure modes, so not a full 5.

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

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

Four short, front-loaded sentences; the primary action leads, followed by routing guidance and behavioral constraints. 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?

With no output schema, the description compensates by stating what a call yields (a new link plus an expiry) and the auth prerequisite. For a 3-param creation tool, 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?

Schema description coverage is 100%, so the schema already documents connector, identifier, and environmentId. The description's examples ('such as Notion or Gmail') merely echo the schema, adding no meaning beyond it — 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 (Create) and resource (a link that connects an OAuth connector account) with concrete examples (Notion, Gmail). It also scopes the action to 'one environment' and explicitly distinguishes itself from catalog-search 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?

Names both alternatives and the condition that selects each: 'Use list_connected_accounts to see accounts that are already connected' and 'This tool does not search the catalog. Use search_connectors for that.' The agent is routed unambiguously.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the mutation profile is covered. The description adds genuinely new behavioral context beyond the annotations: the caller OAuth token requirement and the duplicate-name rejection rule, though it says nothing about response contents or side effects on default role assignment.

Agents need to know what a tool does to the 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 short sentences, each carrying a distinct decision-relevant fact: what it makes, where to look first, what it explicitly does not do, and the auth/prerequisite constraint. The core purpose leads and nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 mutation tool with no output schema, the description covers purpose, alternatives, auth requirement, and the duplicate-name failure mode, which is nearly everything an agent needs. The only minor gap is that it does not hint at what the call returns (e.g., the created role identifier), which an agent invoking this blind might want.

Complex tools with many parameters or behaviors need more documentation. 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 every parameter (roleName, roleDisplayName, environmentId, isDefault, description) is already documented in the schema, including uniqueness and format constraints. The description adds no syntax or format detail beyond that, 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 ('Create one role in an environment') and immediately scopes it against lookalikes by naming create_environment_scope as the tool for permission scopes. An agent can distinguish it from both list_environment_roles and create_environment_scope 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 explicit routing: use list_environment_roles to see existing roles, use create_environment_scope if a permission scope is needed rather than a role. It also flags an edge condition (duplicate role name rejected) that affects when the call will succeed.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower, yet the description still adds real context: it requires the caller's OAuth token and rejects duplicate scope names. It stops short of describing the failure shape or what resource is returned, so it is strong but not exhaustive.

Agents need to know what a tool does to the 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 short sentences, front-loaded with the core action, then routing, then prerequisites and error behavior. No filler and no restatement of the tool name.

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

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

With no output schema, the description should ideally hint at the return value or the resulting scope identity, which it omits. Everything an agent needs to invoke it correctly — auth requirement, uniqueness rule, sibling routing — is present, so the gap is minor.

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

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

Schema description coverage is 100% with 3 parameters, all documented including the env_<id> pattern and the uniqueness constraint on scopeName. The description repeats the uniqueness rule already in the schema but adds no syntax or format detail beyond it, 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?

Opens with a specific verb+resource ('Create one permission scope in an environment') and immediately disambiguates from the closest sibling by stating 'This tool does not create a role. Use create_environment_role for that.' An agent can select it 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?

Explicitly names two alternative routes: list_environment_scopes for inspecting existing scopes and create_environment_role for the adjacent-but-different operation. Both the when-to-use and when-not-to-use cases are stated directly.

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. The description adds genuinely new context beyond them: the tool requires the caller OAuth token, and it only creates the organization shell, not its users. It does not state duplicate-name behavior or effects of repeated calls, so it stops short of 5.

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

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

Four short sentences, each carrying distinct information (action, sibling for listing, scope boundary, sibling for users, auth requirement), with the core action front-loaded first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 creation tool with no output schema, the description covers scope, prerequisites (OAuth token), and sequencing with the sibling user-creation tool. It omits what the call returns and how name collisions are handled, 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% with only two required parameters, both fully documented in the schema (environmentId format and organizationName). The description adds no syntax, format, or constraint detail 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?

States a specific verb and resource ('Create one organization in an environment') and immediately bounds the scope by declaring what it does not do (create users). An agent can distinguish it from create_organization_user and list_organizations without inspecting 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 routes the agent: use list_organizations to check existing orgs, and use create_organization_user afterward for users. Both a when-to-use and a when-not-to-use (user creation) condition are stated, leaving nothing to inference.

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

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

Adds context beyond the annotations: the tool requires the caller's OAuth token, and it explicitly is not an invitation flow (a genuine semantic distinction given invite_workspace_member exists). It stops short of disclosing what happens when the email already exists or when the role name is invalid, which for a non-idempotent create tool would be valuable.

Agents need to know what a tool does to the 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 short sentences, zero filler, and the core action is front-loaded before the routing alternatives. Every sentence carries a distinct piece of 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 four-required-parameter mutation tool with no output schema, the description covers the action, the auth requirement, and the main sibling disambiguation. It leaves duplicate-email and invalid-role error behavior unstated, which is the only meaningful 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%, including the hint to source the role from list_environment_roles, so the baseline is 3. The description adds no format, constraint, or default information beyond what the schema already documents.

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

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

States a specific verb and resource ('Create one user in an organization and assign a role') and immediately disambiguates from two siblings by name. An agent can tell it apart from invite_workspace_member and list_organization_users 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?

Explicit routing: use list_organization_users to check for existing users, and use invite_workspace_member when the intent is to invite rather than create. The negative case ('does not invite someone to the workspace') is spelled out, which is exactly the confusion an agent would otherwise have.

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 mutation (readOnlyHint=false), no external side effects, idempotency, and non-destructiveness. The description adds a genuinely new operational fact not in the annotations: 'Requires the caller OAuth token.' Its idempotency sentence merely restates idempotentHint=true, so it does not fully earn a 5.

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

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

Front-loads the action, then follows with acquisition step, exclusions, auth requirement, and idempotency in five tight sentences 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 two-parameter toggle with no output schema, the description covers prerequisites, auth, idempotency, and boundary exclusions. An agent has everything needed to call it correctly and interpret the result.

Complex tools with many parameters or behaviors need more documentation. 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 carry format patterns (conn_<id>, env_<id>), so the schema does the heavy lifting. The description adds only the pointer to list_environment_connections for obtaining connection_id, which is helpful but already captured as usage guidance rather than parameter semantics.

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

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

States a specific verb (Enable) plus a precisely scoped resource (one existing environment connection). It immediately distinguishes itself from create_environment_role/create_organization and from list_environment_connections, so an agent can identify what it does without opening the schema.

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

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

Gives explicit positive workflow ('Use list_environment_connections to find the connection id') and two explicit exclusions ('does not create a connection', 'does not enable an organization connection'). This is exactly the when/when-not/alternative pattern.

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 the non-read-only, non-idempotent, non-destructive profile; the description adds that the link is one-time, that each call yields a new link (explaining the non-idempotency), and that a caller OAuth token is required. It stops short of describing link expiry or scope, but adds meaningful behavioral context beyond the annotations.

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

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

Front-loads the core action, then adds routing, exclusion, and auth/return notes in four tight sentences. No filler and every sentence carries distinct information.

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

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

With no output schema, the description covers the return ('a new link') and the auth requirement, which is the key missing structured data. It omits link lifetime/expiry specifics, which would help an agent reason about the returned artifact, leaving a small 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 both required params (environmentId, organizationId) are fully documented in the schema with formats. The description implies a single-organization scope but adds no format or constraint detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

States a specific verb and resource—'Create a one-time admin portal link for one organization'—with scoping to a single organization. An agent can distinguish this from sibling tools like create_organization or update_organization_settings 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 routes the agent: use get_organization_details to read the org, and update_organization_settings for settings changes, while clarifying this tool does neither. When-not guidance is stated directly rather than inferred.

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

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

Annotations already mark this as a safe read, but the description adds material behavioral context beyond them: it requires the caller's OAuth token, it explicitly states the client secret value is NOT returned (a key expectation-setter), and it points the agent to the dashboard for that secret. This is exactly the kind of disclosure a read-credentials tool 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?

Four short sentences, each earning its place, led by the core action and followed by routing, auth, and the secret caveat. No filler, and the most important information is front-loaded.

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

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

With no output schema, the description must convey return values, and it does (client id, env URL, secret suffix as a .env block) while also flagging what is not returned and the auth requirement. Nothing an agent needs to call 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% and the single environmentId parameter is fully documented with its env_<id> format, so the schema carries the load. The description adds no syntax or format detail beyond what the schema already provides, making the baseline of 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 (Read) and enumerates the exact resources returned (API client id, environment URL, secret suffix) plus the output format (.env block). It explicitly distinguishes itself from get_environment_details by naming what that sibling returns instead (environment name and domain, not the client id).

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

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

Names the alternative (get_environment_details) and the condition that selects it, and adds a prerequisite (caller OAuth token). It stops short of a full when/when-not statement for this tool itself, but the routing guidance 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 establish readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds a needed behavioral detail the annotations cannot express: 'Requires the caller OAuth token.' It does not cover not-found behavior, but the added auth requirement is genuine value.

Agents need to know what a tool does to the 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 short sentences, front-loaded with the core action, then disambiguation, then the auth prerequisite. The organizations note is slightly tangential for a single-environment getter, but it prevents a plausible misuse, 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?

For a read-only single-resource getter with no output schema, the description names the returned fields, disambiguates siblings, and states the auth requirement. Only the failure mode (invalid or missing id) 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?

A single parameter with 100% schema description coverage including the env_<id> pattern, so the schema carries format details. The description only restates that lookup is 'by id' without adding syntax or semantics beyond the schema, which is the baseline expectation when coverage is high.

Input schemas describe structure but not intent. Descriptions should explain 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') and resource ('one environment by id') plus the returned fields (type, domain). It is immediately distinguishable from the sibling list_environments by its single-resource 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?

Explicitly routes the agent: use list_environments to discover an id, and use list_organizations instead of this tool for org data. Both the when-to-use and the when-not-to-use cases are spelled out with named alternatives.

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 cover the safety profile (readOnly, idempotent, non-destructive, not open-world), so the bar is lower. The description still adds real context beyond them: the OAuth token requirement and the explicit statement that organization users are not returned. It does not describe the payload shape, which keeps it at 4 rather than 5.

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

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

Four short sentences, each doing distinct work: purpose, discovery alternative, exclusion alternative, auth prerequisite. The core verb+resource is front-loaded 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-param read tool with no output schema, the description covers what to pass, how to obtain the id, what it does not return, and the auth requirement. It does not hint at the returned organization fields, but with annotations carrying safety and the schema carrying both params, that 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% and includes format patterns (env_<id>, org_<id>) for both parameters, so the schema carries the semantics. The description only restates 'by id' and adds no format, resolution, or constraint detail beyond it — the baseline 3 for fully documented schemas.

Input schemas describe structure but not intent. Descriptions should explain 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 with scope: 'Read one organization by id.' It explicitly carves out what it is not ('does not list the organization users') and names the sibling that does, so it is distinguishable from list_organizations and list_organization_users 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 explicit routing: use list_organizations to discover an id, use list_organization_users for user listings. Both when-to-use and when-not-to-use are stated with the alternative named, leaving nothing to inference.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive behavior. The description adds two things annotations cannot: that it requires the caller's OAuth token, and that each call can send a new invite (implying repeated calls produce repeated emails rather than being deduplicated). It stops short of saying what happens if the person is already a member.

Agents need to know what a tool does to the 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 short sentences, purpose first, then the membership-check pointer, then the org-level exclusion, then auth and repetition behavior. No filler or restatement of the tool name.

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

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

With one fully documented parameter, no output schema, and annotations covering the safety profile, the description covers nearly everything an agent needs: scope, alternative, auth requirement, and repeat-call behavior. It omits failure semantics (invalid email, already-a-member), which would be the last useful addition.

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

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

The single parameter is fully described in the schema (100% coverage), so the schema carries the meaning. The description adds only that the invite is scoped to 'the current workspace,' which is context rather than parameter syntax. 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 (invite), resource (workspace member), cardinality (one person) and channel (by email). It also names create_organization_user as the adjacent but different operation, so an agent can distinguish it from sibling tooling 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?

Explicitly gives the alternatives and the boundary: use list_workspace_members to check existing membership, and use create_organization_user if the intent is to add to an organization rather than a workspace. Both a when-to-use check and a when-not-to-use exclusion are present.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context: pagination semantics ('one page at a time') and the OAuth token requirement. It stops short of describing what a fuller result looks like or how the summary grouping affects the 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?

Four short sentences, zero filler, with the core action and scope front-loaded before the routing guidance. Every sentence carries a distinct, actionable fact.

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

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

No output schema exists, so return-shape disclosure rests on the description; it conveys paging and that accounts group by connector only indirectly via the schema's summary param. Given 100% schema coverage and annotations covering safety, this is close to complete, with only return-format detail 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% for all 6 parameters, including the summary/full-detail toggle, pageSize caps, and filter formats, so the schema carries the load. The description adds only the environment scoping already implied by the required environmentId, and contributes no extra syntax or filter guidance.

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

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

States a specific verb+resource ('List connected accounts') plus scope ('in one environment') and then defines the domain object ('the users who authorized a connector'), so an agent knows exactly what entities come back. It also names the closely related siblings it is not, making it distinguishable 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?

Explicit disambiguation: 'Use search_connectors to find a connector in the catalog' and 'Use list_environment_connections for SSO connections, not connector accounts' — both an alternative and an exclusion. The auth prerequisite ('Requires the caller OAuth token') is also stated up front.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds the auth requirement ('Requires the caller OAuth token'), which is genuinely useful context not present in structured fields. It doesn't mention pagination or return shape, keeping it short of a 5.

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

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

Front-loaded with the core purpose, then disambiguation, then a prerequisite. Four short sentences with minimal waste, though the sibling pointers are slightly repetitive in structure.

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

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

For a read-only list tool with full annotation coverage and a fully documented single parameter, the description covers purpose, routing, and auth. Minor gap: no indication of result size, ordering, or pagination behavior.

Complex tools with many parameters or behaviors need more documentation. 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 (environmentId) and schema coverage is 100% with a documented format pattern, so the schema does the work. The description adds no further parameter meaning, which is the expected baseline 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 ('List') and resource ('SSO connections') scoped to one environment. It explicitly names the two closest siblings it is not, so an agent can distinguish it without opening schemas.

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

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

Gives explicit routing: use list_organization_connections for organization-scoped connections and list_connected_accounts for OAuth connector accounts. The clarifying note 'Those are a different record' removes ambiguity about record type.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral prerequisite — the caller OAuth token requirement — that annotations do not convey. It stops short of mentioning pagination or result volume, so not a 5.

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

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

Four short sentences, front-loaded with what it does, followed by routing guidance and the auth requirement. No sentence is redundant and nothing is 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 single-parameter read-only list tool this covers purpose, routing, exclusions, and the auth requirement. The only unaddressed gap is what a returned role object looks like, which matters slightly since no output schema exists to fill that in.

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

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

Single parameter with 100% schema description coverage, so the schema already documents environmentId and its env_<id> format. The description only implies scoping to "one environment" and adds no syntax 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?

Specific verb + resource + scope: "List roles defined in one environment." It explicitly distinguishes itself from create_environment_role and list_environment_scopes, so an agent can tell it apart from siblings without opening schemas.

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

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

Names two alternatives with their selecting conditions: create_environment_role for adding roles, list_environment_scopes for permission scopes. It also states an explicit exclusion ("does not list permission scopes"), leaving nothing to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds two useful facts beyond that: results are paginated ('one page at a time') and the call requires the caller's OAuth token. It stops short of describing ordering or return shape, but that is a minor 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?

Four short sentences, each earning its place: what it does, the discovery use case, the sibling alternative, and the auth prerequisite. Purpose is front-loaded with zero 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 read-only list tool with full annotation coverage, complete parameter docs, and no output schema, the description covers purpose, usage routing, pagination, and auth. It is essentially complete; only environment field contents are unmentioned, which is acceptable given 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%, so pageSize and pageToken are already fully documented in the schema. The description only reinforces pagination ('one page at a time') without adding format or semantics beyond what the schema states. Baseline 3 is appropriate when the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain 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 (environments) scoped to the current workspace, and explicitly distinguishes itself from get_environment_details. An agent can differentiate it from its siblings without opening any schema.

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

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

Gives explicit when-to-use guidance ('discover environment ids') and names the alternative with its selecting condition ('use get_environment_details when you already have an id'). The boundary between discovery and detail-lookup 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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety/behavior profile is fully covered by structured fields. The description adds one genuine value: 'Requires the caller OAuth token', an auth prerequisite not encoded in annotations. It says nothing about pagination or result ordering, so it clears the (lower) annotated baseline without being rich.

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

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

Three short sentences, each load-bearing: purpose, alternative for creation, disambiguation from roles, plus auth requirement. Front-loaded with the primary action and 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-param, read-only list tool with full schema coverage and no output schema, the description supplies everything an agent needs: exact scope, the sibling it must not be confused with, the creation alternative, and the auth requirement.

Complex tools with many parameters or behaviors need more documentation. 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 environmentId parameter is fully documented in the schema (format, pattern). The description adds no parameter-level detail, which is appropriate at baseline 3 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 (List) and resource (permission scopes) scoped to one environment. It explicitly disambiguates from the closely-named sibling list_environment_roles ('This tool does not list roles. Use list_environment_roles for those.'), which is exactly the confusion an agent is most likely to hit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routing: use create_environment_scope to add a scope, and use list_environment_roles to get roles. This covers the two most likely alternative intents. It does not explicitly state when-not to use this tool in general (e.g., cross-environment listing), 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: pagination behavior ('one page at a time') and the OAuth token requirement, both of which the annotations do not 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?

Four short sentences, with the core purpose front-loaded ahead of the routing hints and the auth prerequisite. No filler and no repetition of schema or annotation content beyond what adds value.

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

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

For a two-parameter paginated list tool with full schema coverage and an output schema absent, the description covers purpose, alternatives, pagination, and the auth requirement. Nothing critical for correct invocation is missing, though it says nothing about what a page contains or total counts.

Complex tools with many parameters or behaviors need more documentation. 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 pageToken's description ('Page token from a previous list response. Omit it to read the first page.') is already fully documented in the schema. The description's 'one page at a time' phrasing only loosely echoes this, adding no syntax or format detail beyond 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+resource+scope: 'List MCP servers registered in one environment, one page at a time.' It explicitly names the two closest siblings (register_mcp_server for adding, update_mcp_server for changing), so an agent can distinguish intent 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?

Routes the agent to the right alternative for add/change operations, which is the main selection decision for this family. It does not cover when this list would be preferred over related list tools, but for a CRUD-list tool the guidance is clear and 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds non-annotation context that matters operationally: it 'Requires the caller OAuth token'. It does not mention pagination or result volume, which is the only material 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?

Four short sentences, each carrying a distinct job: what it does, the two exclusions, and the auth prerequisite. The purpose is front-loaded in the first sentence 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 read-only list tool with no output schema and fully documented params, the description covers scope, sibling disambiguation and auth. Only the return shape (e.g. pagination or empty-result behavior) is unaddressed, which is a minor gap given the low 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% and both parameters (environmentId, organizationId) are documented with format patterns in the schema itself. The description only implies that organizationId scopes the result; it adds no format, ordering, or filtering detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List SSO connections') and explicitly narrows scope to 'one organization', which distinguishes it from the environment-level sibling without requiring the caller to open 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?

Names the two alternative tools and the exact condition selecting each: use list_environment_connections for environment-wide connections, and enable_environment_connection (not this tool) to enable a connection. Nothing is left to inference about when this tool is the wrong choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false. Beyond that, the description adds two genuinely useful behavioral facts: pagination ('one page at a time') and an auth requirement ('Requires the caller OAuth token'). It does not explain page size limits or response shape, but the pagination and auth disclosures exceed what annotations provide.

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

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

Three tight sentences, each earning its place: purpose+scope, sibling routing, and auth prerequisite. Front-loaded with the core action.

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

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

Complete enough for a read-only, paginated list tool: purpose, alternatives, pagination, and auth are all covered. A minor gap is the absence of response shape or page-size guidance, though no output schema exists to carry it.

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

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

Schema coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description adds the pagination model ('one page at a time') which contextualizes pageToken beyond its schema text, and ties environmentId to a single-environment scope.

Input schemas describe structure but not intent. Descriptions should explain 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 (organizations) with scope (one environment). Explicitly distinguishes itself from get_organization_details and create_organization by naming both siblings and their conditions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routing: use get_organization_details when you have an id, use create_organization to add one. This tells the agent when to use this tool vs two specific alternatives, leaving nothing to inference.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false and a closed world, so the safety profile is covered. The description adds meaningfully beyond that by disclosing the auth requirement ('Requires the caller OAuth token') and the paginated nature of the result — both non-obvious operational facts.

Agents need to know what a tool does to the 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, front-loaded sentences: scope first, then sibling routing, then the auth prerequisite. No filler and 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 simple paginated read with full annotation coverage and a complete schema, the description covers purpose, routing and the OAuth prerequisite. Return shape isn't described (no output schema, but the pagination hint and pageToken param convey continuation behavior), so the remaining gap is minor.

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

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

Schema description coverage is 100%, and the schema already documents pageToken, environmentId and organizationId with formats and defaults. The description's only added nuance is the page-at-a-time framing, which is largely redundant with the pageToken description. 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 users in one organization') plus the pagination scope ('one page at a time'). It then names the adjacent siblings (get_organization_details, create_organization_user), so an agent can place it precisely within the organization/user tool family.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routes the agent to the right siblings by stating what each is for ('use get_organization_details to read the organization record', 'use create_organization_user to add a user'), which implicitly distinguishes enumeration from read/write of a single org or user. It stops short of an explicit selection condition or a 'do not use this for X' exclusion, so it is strong context rather than a full decision rule.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower. The description adds a real behavioral fact not in the annotations: it requires the caller OAuth token. It does not describe return shape or scoping caveats, but the auth requirement is meaningful added context.

Agents need to know what a tool does to the 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 read scope, then the alternatives, then the auth prerequisite. No filler; every sentence carries information.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description tells the agent what is returned (all three URI categories), how to change them, and the auth requirement. Nothing needed 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% and there is only one parameter (environmentId) fully documented in the schema with its pattern. The description adds no syntax or format detail beyond what the schema already provides, 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 ('Read') and enumerates the exact resources returned: login redirect URIs, the initiate-login URI, and post-logout redirect URIs, scoped to one environment. This clearly separates it from the mutating siblings in the redirect-URI family.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 three alternative tools (add_redirect_uri, set_initiate_login_uri, add_post_logout_redirect_uri) and the condition that selects them ('to change one of those values'), making the read-vs-write decision 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds two useful facts beyond annotations: the OAuth token requirement and the paginated ('one page at a time') behavior. It stops short of describing cursor/next-page semantics for the response.

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

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

Four short sentences, each earning its place: action, add-alternative, exclusion, auth requirement. Front-loaded with the primary purpose and 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 read-only, no-output-schema list tool, the description covers purpose, alternatives, exclusion and auth. The only modest gap is how paging resolves (next page token / termination), which is not explained, but the essentials for correct invocation are present.

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

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

Schema description coverage is 100% and the single pageToken parameter is fully documented there as a 1-based page number with default. The description only restates pagination in prose ('one page at a time') without adding format or bounds beyond the schema, 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 ('List members of the current workspace') with pagination scope, and explicitly disambiguates from the sibling list_organization_users. An agent can select it correctly 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?

Names the alternative for the org-wide case ('This tool does not list users inside an organization. Use list_organization_users for those') and routes to invite_workspace_member for the add operation. Explicit when-to-use and when-not-to-use guidance with named siblings.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, closed-world behavior. The description adds genuinely new context: an OAuth token is required, the returned metadata must be published at /.well-known/oauth-protected-resource, and the passed URL becomes the token audience.

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

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

Five short sentences, each carrying distinct information (purpose, alternatives, auth requirement, publish instruction, audience semantics). Front-loaded with the core action and free of 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 7-parameter mutation tool with no output schema, the description covers the action, prerequisites, alternatives, and the meaning of the returned metadata. It does not detail the structure of the returned protected-resource metadata, but the operational guidance is otherwise 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 coverage is 100%, so the baseline is 3. The description goes further by explaining the cross-cutting consequence of mcpServerUrl — it becomes the token audience — which the schema states but reinforces operationally, and it clarifies the auth-token prerequisite for the 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 and resource — 'Register one MCP server in an environment' — and the side effect of returning protected-resource metadata. It is unmistakably distinct from list_mcp_servers and update_mcp_server, which are named directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routes the agent: use list_mcp_servers to view existing servers and update_mcp_server to modify an existing one. The 'one server' scope and the create-then-modify boundary leave nothing to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations — the OAuth token requirement — and confirms the destructive semantics ('This deletes the URI'), though it says nothing about what happens on repeated calls or when no URI is set.

Agents need to know what a tool does to the 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 short sentences, front-loaded with the purpose before alternatives and the auth note. The trailing 'This deletes the URI' is largely redundant with destructiveHint=true, so it does not earn its place as strongly as the rest.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, no-output-schema tool, the description covers purpose, alternatives for the set and read cases, and the authentication requirement. Return values need not be explained, and nothing an agent needs to invoke this correctly appears 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?

There is a single parameter with 100% schema description coverage (including the env_<id> format pattern), so the schema carries the parameter semantics. The description adds no format or constraint detail beyond naming the environment, which is the expected 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 first sentence states a specific verb and resource ('Clear the initiate-login URI for an environment'), which is unambiguous and separable from sibling operations like remove_redirect_uri or set_initiate_login_uri. An agent can identify the target resource and the mutation 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 explicitly routes to two named alternatives with their conditions: set_initiate_login_uri for setting a new value and list_redirect_uris for reading the current one. It also states the authentication prerequisite ('Requires the caller OAuth token'), leaving little to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds value beyond them by stating the caller's OAuth token requirement and clarifying that the URL is deleted from the allowed list, though it says nothing about error behavior or whether removal affects existing sessions.

Agents need to know what a tool does to the 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 short sentences, front-loaded with the core action before the alternatives. Slightly redundant in that 'Remove one post-logout redirect URL' and 'This deletes that URL from the allowed list' restate the same fact, costing a bit of economy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 the action, the auth prerequisite, the destructive nature, and the sibling routing. Annotations handle idempotency and openness, so nothing essential is missing, though a note on failure modes 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 coverage is 100% and both parameters are already documented with format and pattern constraints, so the schema carries the load. The description adds only that the URL comes from the post-logout redirect list, which is marginal over the schema's own wording. 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 (Remove) and resource (post-logout redirect URL) scoped to an environment, and explicitly contrasts it with the similarly-named remove_redirect_uri (login callback URL). An agent can distinguish it from the redirect-URI siblings 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?

Names two concrete alternatives with the condition that selects them: remove_redirect_uri for login callback URLs and list_redirect_uris to read the current list. Nothing is left to inference about when to pick this tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: the caller OAuth token requirement and confirmation of what is destroyed ("deletes that URL from the allowed list"). It does not say what happens if the URI is absent, which keeps it short of a 5.

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

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

Four short sentences, front-loaded with the action before the routing hints. The final sentence partially restates the opening (removal of the URL), a minor redundancy that keeps it off a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 no output schema and full annotation coverage, the description covers purpose, alternatives, auth requirement and effect. Edge behavior (unknown URI, effect on active sessions) is unstated but not essential to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters (uri, environmentId with its env_<id> pattern) are fully documented in the schema. The description adds no format or constraint detail beyond it, 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 and resource with scope: "Remove one login callback URL from an environment." It also explicitly contrasts itself with the near-identical sibling remove_post_logout_redirect_uri, so an agent can pick 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?

Names two alternatives with the condition that selects each: remove_post_logout_redirect_uri for post-logout URLs and list_redirect_uris for reading the current list. This is exactly the disambiguation needed among the redirect-URI siblings (add_redirect_uri, remove_initiate_login_uri).

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description adds the two behavioral facts annotations cannot express: the caller must supply an OAuth token, and results are paginated one page at a time. It stops short of describing result shape or pagination termination, so it is a genuine but not exhaustive addition.

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

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

Purpose and scope lead, then exclusions, then the auth prerequisite — a sensible front-loaded order with almost no filler. The inline 'Google, Notion, and Slack' examples are compact and earn their place; the four short sentences are only marginally more than strictly needed.

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

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

A six-parameter, paginated search with no output schema needs scope, auth, and pagination called out, and the description covers all three while ruling out the two confusable siblings. The remaining gap — what a returned connector record contains — is not required since no output schema exists, but a brief hint would have made it exhaustive.

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

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

Schema description coverage is 100%, including per-parameter detail for query, pageSize, pageToken, connectorType, environmentId, and includeSetupStatus, so the schema already carries full semantic load. The description only adds the generic 'one page at a time' framing and 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?

Specific verb+resource: 'Search the connector catalog in one environment, one page at a time', with concrete examples (Google, Notion, Slack) that anchor what a connector is. It also distinguishes itself from the two nearest siblings, search_tools and list_connected_accounts, so an agent can route 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?

Explicit when-not guidance and named alternatives: 'Use search_tools to search actions on a connector' and 'This tool does not list connected accounts. Use list_connected_accounts for those.' Both boundaries an agent would otherwise guess at are stated outright.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true. The description adds genuinely new context beyond those: a 50,000-character result cap, no OAuth token requirement, and confirmation it does not mutate records.

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

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

Five short, front-loaded sentences with no padding; the core purpose and the routing rule come first. The final sentence ('does not change any Scalekit record') mildly duplicates the readOnlyHint/destructiveHint annotations, costing a little.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 search tool with no output schema, the description covers purpose, fallback behavior, result-size limits, and auth/mutation profile. Nothing critical is missing, though it says nothing about result ordering, relevance ranking, or pagination.

Complex tools with many parameters or behaviors need more documentation. 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 'query' parameter, so the schema already carries the semantics. The description adds only 'by keyword,' which restates the schema rather than adding syntax or format guidance, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Search public Scalekit documentation by keyword'), which is enough to distinguish it from the search_connectors and search_tools siblings by domain. It does not name those siblings explicitly, so sibling differentiation is implied rather than spelled out.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routing guidance: 'Read a docs:// resource when one resource already covers the topic' and 'Use this tool only when no docs:// resource matches.' Both the when and the when-not, plus the alternative, are stated directly.

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, idempotent, non-destructive behavior, and the description adds real context beyond them: it does not invoke the action, output schemas are not returned, results are paginated one page at a time, and the caller's OAuth token is required. It does not mention rate limits or error behavior, so it falls short of the top of the scale.

Agents need to know what a tool does to the 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 short sentences, front-loaded with the core purpose and immediately followed by the sibling disambiguation. Each sentence carries distinct information (scope, routing, non-execution, auth/response-shape caveat), though the phrasing is clipped enough that the response-shape sentence reads as a loose trailing note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 search tool with no output schema, the description covers what an agent needs: it says output schemas are not returned, points to connector API docs for response shape, notes the OAuth requirement, and the schema fully documents all seven parameters. Nothing essential to a 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 every parameter (query, summary, pageSize, connector, pageToken, identifier, environmentId) is already documented in the schema, making 3 the baseline. The description only obliquely reinforces pagination ('one page at a time') and auth requirements for custom connectors, without adding parameter 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 with scope: 'Search actions exposed by connectors in one environment, one page at a time.' It explicitly differentiates itself from the sibling search_connectors ('Use search_connectors to find the connector itself'), 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?

Gives a clear routing rule to the alternative tool (search_connectors) and clarifies that this tool does not execute the action, which is a strong disambiguation. It stops short of stating when-not to use it beyond that single alternative (e.g. no guidance on query vs connector-only searching).

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds the genuine non-annotation detail that the caller's OAuth token is required. The closing idempotency sentence largely restates the idempotentHint annotation, so it earns credit for the auth requirement rather than full marks.

Agents need to know what a tool does to the 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 definition is well front-loaded: the action comes first, then the resource definition, then alternatives, then preconditions. Five short sentences with only one mild redundancy (the repeated idempotency note) keeping it off a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, non-destructive setter with no output schema, everything an agent needs is present: what the tool sets, what the value means, how to undo it, how to read it, and the auth requirement. No material gap remains.

Complex tools with many parameters or behaviors need more documentation. 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, including the exact wording of the uri semantics and the environmentId format pattern. The description adds little beyond the schema's own parameter documentation, 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 verb+resource ("Set the initiate-login URI for an environment") and then defines what that URI actually is, so an agent understands the resource semantically, not just lexically. It also distinguishes itself from siblings by naming remove_initiate_login_uri and list_redirect_uris, making it unambiguous against the other redirect-URI tools.

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

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

It routes the agent explicitly: use remove_initiate_login_uri to clear, use list_redirect_uris to read. Both the alternative and the condition that selects it are named, which is the strongest form of sibling disambiguation in this tool 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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered; the description adds the caller-OAuth requirement and clarifies that the switch is unconditional ('always sends the switch request'), implying no dry-run/preview. It does not explain reversibility of clearing the external provider, which is the main remaining gap.

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

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

Four short sentences, front-loaded with the core action, and the sibling-routing exclusion follows immediately. The sentence 'The call always sends the switch request' is terse to the point of ambiguity but still earns its place as a no-preview disclosure.

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

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

For a destructive, idempotent, no-output-schema mutation on two required ids, the description covers scope, prerequisite auth, sibling alternative, and absence of field edits. Reversibility/effect on the cleared external provider is left unstated.

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

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

Schema description coverage is 100% and both parameters carry format patterns (app_<id>, env_<id>), so the schema does the heavy lifting. The description adds no parameter-level meaning beyond that, 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?

Names a specific verb+resource: clears the external provider on one registered MCP server and moves it to Scalekit auth. It explicitly distinguishes itself from the sibling update_mcp_server, 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?

States the alternative (update_mcp_server) for name/URL/other fields and explicitly says this tool does not edit those fields, giving a clear when-to-use vs when-to-use-the-other boundary. It also surfaces the prerequisite that the caller's OAuth token is required.

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive, non-open-world mutation, so the safety profile is covered. The description adds the caller OAuth token requirement, which is useful context, but says nothing about partial-update semantics or what happens to the provider on the Scalekit path beyond what the schema states.

Agents need to know what a tool does to the 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, each doing distinct work: what it does, the sibling it is not, and how to get the id. Front-loaded with the core action and zero 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 an 8-parameter mutation tool with no output schema, the description covers purpose, sibling routing, id lookup, and the auth prerequisite, leaving only edge cases like provider-clearing behavior on partial updates unaddressed. Annotations and the fully documented schema carry the remaining burden.

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

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

Schema description coverage is 100%, so every parameter including the 'omit to leave unchanged' semantics is already documented in the schema. The description adds no parameter-level syntax or constraint beyond that 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 (update) and resource (one registered MCP server) and names concrete examples of updatable fields (name, URL). It is clearly distinguishable from siblings register_mcp_server and switch_mcp_auth_to_scalekit, which it explicitly references.

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

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

Names the alternative tool switch_mcp_auth_to_scalekit and the exact condition that selects it ('when the only change is to clear an external provider'), and points to list_mcp_servers to obtain the id. Routing guidance is explicit rather than implied.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, and the description adds a genuinely new behavioral fact: the caller's OAuth token is required. It also bounds the blast radius by stating what the tool will not change. It does not describe the response or partial-application behavior.

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

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

Four short sentences, front-loaded with the core action, then sibling routing, then scope exclusions, then auth. No sentence is filler and nothing is 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 non-destructive, idempotent mutation with no output schema and fully documented parameters, the description covers action, auth, and scope limits. The only missing piece an agent might want is return/confirmation behavior, which is minor given the annotations.

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

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

Schema description coverage is 100%: the features array, its name/enabled sub-fields, and the environmentId/organizationId formats are all documented in the schema. The description only echoes the toggling intent and repeats the dir_sync example, adding little semantics beyond the structured fields, 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 and resource: turning named features on/off for one organization, with a concrete example (directory sync). It also explicitly distinguishes itself from get_organization_details and from out-of-scope operations (rename, add users), so an agent can pick it correctly from the sibling list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routes reads to get_organization_details and rules out renaming and user-adding, which is real when/when-not guidance. It stops short of naming which sibling handles those excluded operations, so the agent must infer the alternative for rename/add-user cases.

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