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

Adds substantial detail beyond annotations: read-modify-append workflow, idempotent success for exact matches, rejection of conflicting settings, and required organization-admin auth. The annotations already cover idempotency/safety, but the description enriches them meaningfully.

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

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

Organized under Purpose/Behavior/Auth/Safety headers, front-loading the key action and constraints with zero filler. Each section earns its space.

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

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

For a mutation tool with nested parameters and no output schema, the description covers behavior, auth, idempotency, and safety checks needed before calling. Complete for decision-making.

Complex tools with many parameters or behaviors need more documentation. 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 75%, and the description adds operational meaning: omitting group_id triggers auto-generation of an independent consumer group, and conflicting settings are rejected. It doesn't document each field's format, but complements the schema well.

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

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

States a specific verb (add), resource type (Kafka topic-to-table destination), and scope (one destination to an existing connector). Distinguishes from create-connector and related connector siblings by emphasizing appending to an existing connector's destination 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?

Clarifies the additive intent ('without changing its current destinations') and semantics (omit group_id for auto-generation; idempotency for identical destinations). It doesn't explicitly name alternative tools, but the design of the tool makes its use context 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?

It adds substantial behavioral context beyond the annotations: the invitation is pending, the user joins with the member role only after accepting, an external email is sent, and admin credentials are required. The safety warning to confirm the exact organization and email before calling is especially valuable for a mutating invitation tool.

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

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

The description is front-loaded with Purpose and organized into Purpose, Returns, Behavior, Auth, and Safety sections. It is somewhat long, but each section adds actionable information rather than repeating structured fields.

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

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

With no output schema, the description explicitly covers return values, pending-invitation behavior, role assignment, authentication requirements, and safety constraints. Nothing material is missing for an agent deciding whether and how to invoke this tool.

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

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

Schema coverage is 100% and both parameters already have descriptions, so the description need not carry the parameter burden. It adds no syntax or format details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: starting to add a member by sending an invitation to an email address. It clearly distinguishes this from list-organization-members and update-organization-member by explaining the pending-invitation lifecycle and post-acceptance promotion path.

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

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

It gives clear usage context, including that the person will not appear in list-organization-members until acceptance and that update-organization-member should be used afterward to promote them. It stops short of naming explicit when-not-to-use conditions or all alternative member-management tools.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the endpoint (POST /v1/keys), the admin-permission requirement, and critically that the returned key is shown only once and MUST be surfaced to the user. It omits secondary traits like rate limits or whether creating a key affects existing keys, keeping it just 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?

Bold-labeled sections (Purpose, NOT for, Returns, Auth, When to use) front-load the identity and the critical warning, and every line earns its place. No filler or restated title.

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

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

No output schema and no annotations, so the description must cover the return value and safety context - and it does, explaining that the key value is returned once and must be displayed, plus the auth prerequisite. Complete for a create-key operation.

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

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

Schema coverage is 100%, so all five parameters (including the permission enum with a default) are already documented in the schema. The description reinforces permission intent ('read-only, write-only, read-write, or admin credential') but adds no syntax or format 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?

States a specific verb and resource - 'Create a new RawTree API key for a cluster' - and explicitly contrasts with a sibling workflow ('NOT for: User login'). An agent can distinguish this from list-api-keys and delete-api-key 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?

Provides an explicit 'NOT for' exclusion naming the alternative (RawTree auth/CLI or dashboard) plus a three-bullet 'When to use' list covering CI/agents/connectors, permission scoping, and rotation. Nothing about when to select this tool is left to inference.

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

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

Annotations only supply readOnly=false, idempotentHint=false, destructiveHint=false. The description goes well beyond: async provisioning continues after acceptance, autoscaling semantics (min/max per replica, fixed replica count), storage fallback behavior, org-admin auth requirement, and the non-idempotent retry guidance. This is substantial additive behavioral 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?

Bold-labeled sections (Purpose, Returns, Behavior, Auth, Safety, Reliability) front-load the essentials and make the dense content scannable. Given 8 parameters, nested objects, and the safety protocol, every sentence earns its place.

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

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

With no output schema, the description supplies the return semantics (new cluster with ID, lifecycle status, initial resources) and covers auth, safety prerequisites, and reconciliation on ambiguity. Nothing an agent needs to invoke this complex mutation 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%, so the baseline is 3, but the description adds relational meaning the schema does not: s3Storage is optional and, when present, drives customer-owned data/backup buckets; databaseS3Access is independent of s3Storage and its externalId must match s3Storage's when both are set; per-database role ARN/destinations belong to create-database. These cross-field constraints are genuinely additive.

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

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

The description opens with a specific verb+resource ('Provision a new RawTree dedicated cluster in an organization'), which unambiguously distinguishes it from siblings like create-database, update-cluster, and delete-database. The scope (dedicated cluster within an org) is explicit.

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

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

It routes the agent precisely: call list-cluster-sizes first, verify-cluster-s3-access before supplying s3Storage, get-cluster to track async progress, and list-clusters to reconcile after an ambiguous response. When-to-use and prerequisite ordering are spelled out 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?

Adds substantial context beyond the annotations: destination tables can be auto-created on first events, each destination gets its own consumer group, admin auth is required, and creation is non-idempotent with a concrete reconciliation step (call list-connectors and match by name). This enriches the idempotentHint=false/destructiveHint=false profile rather than merely restating it.

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

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

Front-loads Purpose and organizes Behavior/Auth/Safety/Reliability as labeled blocks, so it is scannable despite its length. A few points (e.g., the group_id behavior) overlap with schema text, which is mild redundancy.

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

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

For a complex tool with nested objects, no output schema, and low parameter-description coverage, the definition supplies the missing operational context: auth requirements, safety/secret handling, non-idempotency, and reconciliation on ambiguity. Nothing critical to correct invocation is absent.

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

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

Schema coverage is only 33%, but the description only partially compensates: it clarifies group_id omission behavior (which the schema already states), the offset policy, and that SASL values are secrets, while leaving name, type, destinations structure, and most settings subfields unexplained. Marginal value over the schema given the coverage gap.

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

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

States a specific verb and resource ('Create an active Kafka connector') plus scope ('one or more independent topic-to-table destinations'), which distinguishes it from siblings like add-connector-destination and set-connector-status. An agent can identify the operation without opening the schema.

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

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

Gives clear context on when creation applies and its downstream effect ('Consumption starts after the runtime applies the connector'), plus preconditions like org-admin access. It never explicitly names an alternative sibling (e.g., add-connector-destination) or says when-not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and the description goes well beyond them: it states org-admin auth is required, that the operation is not idempotent, and prescribes reconciliation via list-databases if the response is ambiguous. It also explains the inheritance semantics of s3Storage, which no structured field conveys.

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

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

Bold section headers (Purpose, Returns, Behavior, Safety, Auth, Reliability) front-load the essentials and make scanning easy. It is longer than a one-liner, but each section carries distinct operational information rather than 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 non-idempotent mutation with a nested optional object and no output schema, the description supplies everything missing: return contents (created database plus organization context), auth requirements, idempotency behavior, verification workflow, and failure recovery. Nothing an agent needs to call this correctly is absent.

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

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

Schema coverage is 100%, so the schema already documents name, cluster, and organization, but the description adds real semantics: s3Storage is optional, omitting it uses the cluster default, tables inherit the configured storage unless they override, and destination paths are optional while buckets/roleArn/externalId are required inside s3Storage. That is genuine value beyond the schema, though the required/optional structure is also visible in the schema itself.

Input schemas describe structure but not intent. Descriptions should explain 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 precise verb and resource with scope: 'Create a database in a RawTree organization and cluster.' An agent can immediately distinguish this from create-cluster, create-table, and delete-database in 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?

The Safety section gives explicit preconditions: call list-databases and confirm organization/cluster/name/S3 config with the user, and call verify-database-s3-access with identical config when s3Storage is provided. It also states the invalidation rule (never reuse verification after changing any s3Storage field), which is exactly the kind of when-to-use guidance agents need.

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 substantial context beyond the annotations: the storage inheritance order, the fact that the API does not return S3 credentials in cluster metadata, the required organization-admin authorization, and a reconciliation path via list-tables before retrying. These are non-obvious traits annotations cannot express.

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

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

Bold section headers front-load purpose and behavior, and each section earns its place. The Credentials and Auth blocks are slightly verbose relative to the single required parameter, so it falls short of 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 mutation tool with a nested S3 object and no output schema, the description covers return contents, auth, credential caveats, inheritance behavior, and failure recovery. Nothing an agent needs to call it correctly is missing.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning: the omission-inheritance semantics of s3Storage, that paths default to the bucket root, and that externalId must exactly match the value configured in AWS. This goes past what the schema 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 an empty RawTree table in a database') plus the optional S3 storage variant, which cleanly separates it from create-database and create-cluster siblings. An agent can tell what it produces (an empty table) 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 clear conditional guidance: omit s3Storage to inherit database then cluster default storage, or supply a complete s3Storage object for an explicit override, and names list-tables as the tool to reconcile an ambiguous response. It lacks an explicit statement of when NOT to use it versus create-database/create-cluster, keeping it below a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes further by disclosing irreversibility ('This action cannot be undone'), the downstream consequence (services using the key lose access), the accepted key formats, and a required confirmation protocol. This is exactly the extra context annotations cannot carry.

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

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

Bold section labels (Purpose/NOT for/Returns/Safety) front-load the essential facts and make scanning easy, with each block contributing distinct information. The formatting is slightly heavier than a two-sentence description would need, but nothing is 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 destructive, no-output-schema tool, the description covers return value ('Deletion confirmation'), safety profile, identifier formats, and scope exclusions. An agent has everything needed to invoke it correctly and responsibly.

Complex tools with many parameters or behaviors need more documentation. 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 cluster, organization, and idOrApiKey are already documented. The description restates that the key may be given as a UUID or a full rt_ value, which mirrors the schema rather than adding new semantics; baseline 3 applies.

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

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

States a specific verb+resource ('Permanently revoke and delete a RawTree API key') and names the accepted identifier forms (UUID or full rt_ key value). The 'NOT for' line explicitly excludes sibling operations like delete-table, delete-database, and session deletion, so the agent can disambiguate from the many delete/list 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?

Explicitly says when not to use it (tables, databases, sessions) and prescribes a mandatory pre-flight workflow: list/identify the key first, obtain user confirmation of the exact name or ID, and warn about access loss. There is no reliance on 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 destructiveHint annotation, it discloses that deletion is permanent, removes all contained data, cannot be undone, returns a deletion result, and is governed by RawTree API authorization. This is rich behavioral context for a destructive operation.

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

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

The description is structured under Purpose, Returns, Safety, and Auth headings. Each section is short, front-loads the purpose, and every sentence adds actionable information.

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

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

For a destructive tool with no output schema, the description covers the return shape, irreversibility, authorization, and required confirmation steps. An agent has enough context to call it correctly and safely.

Complex tools with many parameters or behaviors need more documentation. 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 the cluster, database, and organization parameters. The description reinforces that all three values must be confirmed exactly but adds no syntax or format details beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Permanently delete a RawTree database and all data it contains.' It clearly distinguishes this destructive database operation from sibling tools like create-database, list-databases, and delete-table.

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

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

It gives an explicit mandatory workflow: list databases first and ask the user to confirm the exact organization, cluster, and database name before calling. This directly addresses when and under what precautions to use the 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?

Beyond the destructiveHint=true annotation, the description adds critical operator context: an admin key is required, the action cannot be undone, and the agent MUST confirm the exact table name with the user first. These are meaningful behavioral disclosures not present in the annotations or schema.

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

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

Bold headers (Purpose/NOT for/Returns/Safety) front-load the identity, the exclusions, and the safety constraint in four tight lines with no filler. Every section carries actionable content.

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

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

For a destructive single-target operation with no output schema, the definition covers purpose, disambiguation, return confirmation, auth requirement, irreversibility, and the pre-call confirmation step. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description only reinforces the 'exact table name' requirement already implied by the schema, adding no new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a RawTree table and its data'), clearly distinguishing it from siblings like create-table, delete-database, and run-query. The scope ('the whole table') makes the target unambiguous.

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

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

The 'NOT for' section gives explicit exclusions ('Clearing a query result or undoing a single insert'), telling the agent when this tool is the wrong choice. This is exactly the when-not guidance the dimension rewards.

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?

No annotations are provided, so the description carries the full burden. 'Inspect' and the return summary make the read-only, non-mutating nature clear, but there is no disclosure of permission/authorization requirements, behavior on a non-existent table, or any rate/latency characteristics. Adequate but incomplete for an annotation-free tool.

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

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

Front-loaded with a bolded Purpose line, followed by tight sections for exclusion, returns, and usage. Every sentence carries distinct information and nothing is repeated.

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

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

With no output schema, the description correctly steps in with a 'Returns: Table metadata and columns' line, and covers purpose, alternatives, and usage triggers. It is complete for a read-only metadata tool, though it stops short of describing error/empty-table 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?

Schema description coverage is 100%, so all four parameters (table, cluster, database, organization) are already documented in the schema, including the database override default. The description adds no syntax, format, or defaulting 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 ('Inspect') and resource (a RawTree table), and enumerates the exact metadata returned: columns, row count, byte count, database, organization. It also explicitly distinguishes itself from run-query, so an agent can tell it apart from siblings like list-tables and run-query 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?

Provides both an explicit exclusion ('NOT for: Sampling actual row values. Use run-query for SELECT queries') and three concrete when-to-use triggers (pre-SQL field discovery, debugging missing columns, post-insert schema inspection). The alternative tool is named with the condition that selects it.

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

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

With readOnlyHint=true already declaring the safe-read profile, the description still adds real value: the full return shape, that role ARNs and secret credentials are never exposed, and that auth requires a user access token plus organization membership. It does not cover rate limits or error behavior, keeping it just below top 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?

Bold section headers front-load purpose and returns, and every block earns its place given the missing output schema. The Returns paragraph is dense but justified by the need to describe the response without a schema.

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

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

No output schema exists, so the description proactively covers return values, credential non-exposure, auth requirements, and the decision context relative to list-clusters. 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 both parameters are documented there ('Dedicated cluster ID returned by list-clusters', 'Organization containing the cluster'). The description adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb, resource, and scope ('Get one RawTree dedicated cluster and its current lifecycle status'), which cleanly separates it from the sibling list-clusters. An agent can distinguish it without opening the schema.

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

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

The 'When to use' block gives three concrete triggers plus an explicit anti-condition ('You already have a cluster ID and do not need the full organization cluster list'), routing the agent away from list-clusters.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it enumerates what is returned (status, sanitized settings, destinations/topics/consumer groups, revision, timestamps) and explicitly states credentials are never returned, which is a useful security-relevant guarantee.

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

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

Bold-labeled Purpose/Returns/When-to-use sections make it front-loaded and scannable, with no filler. Slightly header-heavy for three short blocks, but 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?

With no output schema, the description correctly compensates by describing the return payload and the credential-exclusion behavior. Combined with full schema coverage and read-only annotations, an agent has enough to call it correctly; only deeper pagination/error semantics are 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%, so connectorId, cluster, and organization are all documented in the schema itself (connectorId even notes it comes from list-connectors/create-connector). The prose adds no further parameter detail, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Get one managed connector and its complete public configuration'). The scope word 'one' plus 'complete public configuration' implicitly separates it from list-connectors (many) and get-connector-metrics (metrics only), so an agent can route correctly.

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

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

The 'When to use' section gives a concrete trigger: inspect the latest connector before adding a destination or changing its status. This ties it to the add-connector-destination and set-connector-status workflows, though it does not explicitly name those siblings as 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description goes further by disclosing that counters are cumulative and must be sampled twice to derive rates, and that applying/unavailable statuses carry an explanatory message. That is genuinely useful operational context beyond the structured fields, though permissions or required connector state are not mentioned.

Agents need to know what a tool does to the 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 Purpose/Returns/Interpretation structure is front-loaded and each block carries distinct information; the Returns enumeration is long but earns its place because no output schema exists. Slightly verbose but no filler sentences.

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

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

With no output schema, the description compensates by enumerating returned fields and explaining how to interpret cumulative counters and status messages. It stops short of covering prerequisites (e.g., whether the connector must be running) or auth needs, but is otherwise sufficient for correct invocation.

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

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

Schema description coverage is 100%, and the schema already documents cluster, connectorId (with provenance from list-connectors/create-connector), and organization. The description adds no syntax or format detail for these parameters, 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 ('Read current health and runtime counters') plus scope ('for one connector and each destination'), which cleanly separates it from sibling get-connector (configuration) and list-connectors (enumeration). An agent can pick this tool without opening any schema.

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

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

The scope wording implies when the tool is appropriate (runtime health of a single connector), but there is no explicit when-to-use/when-not statement and no named alternative for related needs such as get-connector or list-logs. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the call is blocking ('Waits for the import to complete'), the public-URL requirement, and the return shape (inserted row count or null). It does not cover error behavior, permissions/auth for RawTree itself, or whether existing rows are affected, leaving some behavioral gaps.

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

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

Front-loaded with Purpose, then scoping, returns, and workflow in clearly labeled sections. Each block earns its place and nothing is redundant padding; trigger phrases aid selection without bloating the text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 ingestion tool with no output schema and no annotations, the description is largely complete: it explains what happens (blocking import), what is returned, and the preconditions. It could go further on error handling and authentication, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including url, table, cluster, database, and organization. The description adds only the 'public URL' constraint, which the schema also states, so it does not meaningfully extend parameter meaning beyond structured data. 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 (ingest JSON/JSONL from a public URL) and resource (into a table), and explicitly scopes it against alternatives by declaring what it is NOT for (private/authenticated URLs). An agent can distinguish it from insert-json 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?

Provides an explicit 'When to use' list, a 'NOT for' exclusion, and a workflow (confirm URL is public → call → verify with list-logs/run-query). It even hints at the sibling alternative by contrasting with data 'too large or inconvenient to paste into the MCP call.'

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

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

No annotations are provided, so the description carries the full burden. It discloses auto table creation on first insert, the return shape ({inserted: n}), and a verification workflow. It omits auth/permission requirements, failure modes, and behavior on schema conflicts, leaving some gaps for a write tool.

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

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

Front-loaded with Purpose, NOT for, Returns, When to use, and Workflow. Structured and scannable, though the trigger-phrase list is somewhat redundant with the When-to-use bullets.

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

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

Covers purpose, exclusions, return shape, workflow, and verification steps without an output schema. Adequate for a write tool, though auth context and error behavior are absent.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description adds little parameter-level meaning beyond the payload workflow narrative. Baseline 3 is appropriate 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 (Insert) and resource (JSON objects into a RawTree table), and explicitly distinguishes from the sibling insert-from-url. The auto-create-table behavior is a concrete distinguishing trait.

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

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

Provides an explicit 'When to use' list with three concrete triggers, a 'NOT for' exclusion naming the sibling alternative insert-from-url, and key trigger phrases. Routing 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses the exact auth requirement ('organization admin access'), notes authorization is server-enforced, states the semantic effect on the cluster, mandates user confirmation, and even summarizes the return shape. Nothing here contradicts the annotations; idempotency and non-destructiveness are consistent with 'install.'

Agents need to know what a tool does to the 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, bold-labeled sections with the purpose front-loaded; an agent can scan it in seconds. It is slightly padded by the redundant sentence 'Authorization is enforced by the RawTree API,' which restates that auth is required without new information.

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

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

For a 3-param mutation with no output schema, the definition covers everything needed: purpose, auth, safety warning, confirmation requirement, and the returned fields. No critical decision input is left to inference.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema (appId from list-apps, cluster from list-clusters, organization). The description only echoes these names in the confirmation sentence and adds no format, source, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource+scope: 'Install a RawTree app on one cluster,' and adds the effect ('enable its native endpoints'). It is clearly distinguishable from siblings like uninstall-app and list-apps in practice, but it never names an alternative, so it falls short of the explicit sibling differentiation required for a 5.

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

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

It gives a concrete pre-call precondition ('You MUST confirm the exact organization, cluster name, and app ID with the user'), which is real usage guidance an agent must obey. It does not, however, state when to prefer this over alternatives or what conditions make installation inappropriate, so it stops short of explicit when/when-not routing.

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

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

With no annotations provided, the description carries the behavioral burden and does well: it states the underlying endpoint (GET /v1/keys) and the auth requirement (admin database API key). It does not disclose pagination behavior or rate limits, which keeps it from a 5 for a list operation with potentially large results.

Agents need to know what a tool does to the 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 bolded Purpose/NOT for/Returns/Auth/When to use structure is front-loaded and scannable. It is slightly longer than necessary for a two-parameter list tool, but every section 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 list tool with no output schema and no annotations, the description covers purpose, exclusions, return fields, auth, and use cases. It omits pagination and error behavior, but it is otherwise complete enough to call correctly.

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

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

Schema coverage is 100%, so the schema already documents both cluster and organization parameters, making 3 the baseline. The description adds no format or scoping detail beyond what the schema provides.

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

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

The description opens with a specific verb+resource ('List API keys for a RawTree cluster') and explicitly distinguishes from the sibling tools create-api-key and delete-api-key under a 'NOT for' header. An agent can select this tool with confidence without inspecting 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?

It gives explicit 'When to use' bullets (audit keys, get key ID before revoking, audit permissions) and names the alternatives to avoid. This is the strongest form of routing guidance and leaves 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 readOnlyHint=true and destructiveHint=false, but the description adds meaningful context beyond them: the auth requirement (user credential + organization membership) and the exact return content. It doesn't mention pagination or catalog size limits, 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?

Front-loaded with labeled Purpose/Returns/Auth/When-to-use sections that scan quickly. Every sentence carries distinct information 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?

No output schema exists, so the description's Returns section is doing necessary work by describing the cluster metadata and per-app fields. Combined with the auth note and usage triggers, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and both parameters are already documented (cluster 'returned by list-clusters', organization). The description only restates the cluster scoping, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (RawTree app catalog plus installation state) scoped to a single cluster. An agent can distinguish it from install-app/uninstall-app 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?

Provides an explicit 'When to use' list: obtaining a valid app ID before install/uninstall, checking installed apps, and verifying state after a change. This directly routes the agent relative to the install-app and uninstall-app 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?

With no annotations, the description carries the full burden and does well: it discloses that a user access token and organization membership are required, that authorization is API-enforced, and that Role ARNs and secret credentials are never returned. It does not mention pagination, rate limits, or result ordering, which are the remaining gaps for a list operation.

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

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

The markdown sectioning (Purpose/Returns/Auth/When to use) is well front-loaded and every section maps to a decision the agent must make. The Returns section is somewhat verbose relative to a list tool, but no sentence is wasted.

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

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

With no output schema in the structured data, the description fully compensates by enumerating returned fields (IDs, names, creation times, lifecycle status, resources, pause/resume flags, s3_storage and database_s3_access metadata) and calling out sensitive exclusions. 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?

There is a single required parameter with 100% schema description coverage, so the schema already fully documents 'organization'. The description adds no syntax, format, or behavioral detail about the parameter beyond what the schema states; 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 (List) and resource (RawTree dedicated clusters) scoped to an organization, and the 'When to use' section distinguishes it from create-cluster by framing it as inspection before provisioning. An agent can tell it apart from get-cluster and list-organizations 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?

The explicit 'When to use' bullets give three concrete triggering scenarios (which clusters exist, need a cluster ID/status, inspect resources before creating another). It stops short of explicit exclusions or naming sibling alternatives like get-cluster for a single cluster, so it is clear context without full routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds non-obvious context beyond that: the auth requirement (user credential such as OAuth, enforced by the RawTree API) and the mandatory call-before-create-cluster sequencing driven by a 'current backend-controlled catalog' that can change.

Agents need to know what a tool does to the 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 labeled sections, each front-loaded and each earning its place: purpose, return contents, auth, and the critical call-ordering rule. No filler or restatement of the name.

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

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

With no output schema, the description compensates by enumerating what comes back (per-replica sizes, min/max replica counts, default vertical autoscaling bounds). Combined with the auth note and the mandatory pre-create-cluster ordering, an agent has everything needed to call this correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter guidance, and its 'Returns' section describes the output shape rather than inventing inputs.

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

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

States a specific verb (List) and a precise resource (RawTree cluster creation options: per-replica sizes, replica counts, autoscaling bounds). This is clearly distinguishable from sibling list-clusters, which enumerates clusters rather than the catalog of valid sizes.

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

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

Explicitly states when to use it and imposes a hard ordering constraint: 'You MUST call this tool before create-cluster so replicas and both sizes come from the current backend-controlled catalog.' The alternative/blocking relationship with a named sibling is spelled out, 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 readOnlyHint=true and destructiveHint=false, so safety is covered, but the description goes further: it enumerates returned fields, explicitly states credentials are never returned, and warns connector management may be unavailable in some environments — genuine behavioral context beyond the annotations.

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

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

Three bold-labelled sections keep Purpose, Returns, and Auth front-loaded and scannable with no filler sentences. Slightly expository for a list tool, but 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?

With no output schema, the description compensates by enumerating return fields, and it also covers auth and availability caveats. Only gap is pagination/volume behavior for a list operation, which an agent might care about.

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

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

Schema description coverage is 100%, so the schema already documents both 'cluster' and 'organization'. The description echoes cluster scoping but adds no format or semantics beyond what the schema supplies, which is the baseline case.

Input schemas describe structure but not intent. Descriptions should explain 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 (managed connectors) plus the scope constraint (one RawTree cluster). An agent can distinguish this from get-connector, create-connector, and add-connector-destination 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?

The listing/scope semantics imply when to call it, and the auth sentence gives useful preconditions (user credential + organization membership), but there is no explicit when-to-use vs alternatives routing (e.g., 'to inspect a single connector, use get-connector'). Usage is inferred rather than stated.

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

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

With no annotations present, the description carries the full burden and does disclose meaningful return semantics (s3_storage metadata, null = inherits cluster default) and a security guarantee ('credentials are never returned'). It omits auth/permission requirements and rate-limit or pagination behavior, which keeps it below 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?

Well front-loaded with a bold 'Purpose' line and organized into Returns/When-to-use sections; every block carries information. Slightly verbose with its header scaffolding, but nothing is 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?

There is no output schema, so the description correctly assumes responsibility for explaining return values, and it does so including the s3_storage nuance. Given zero required params and full schema coverage, this is nearly complete; only auth/prerequisite-permission context 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 both parameters (cluster, organization) are already documented in the schema, so the baseline of 3 applies. The description adds no syntax, format, or defaulting guidance beyond what the schema provides.

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

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

States a specific verb and resource ('List databases') plus the scope ('in a RawTree organization and cluster'), which is more precise than the name alone. An agent can distinguish it from list-tables, list-clusters, and delete-database 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?

The 'When to use' section gives concrete triggering conditions, including the prerequisite relationship ('need a database name before using query, table, ingest, or log tools'). It stops short of naming when NOT to use it or naming a sibling alternative, so it earns 4 rather than 5.

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

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

With no annotations, the description carries the behavioral burden and does well: it lists returned fields, default time window, pagination, origin types, and the exact SQL RawTree saw. It does not state read-only/permission requirements explicitly, and it says 'next_offset' for pagination while the schema exposes an 'offset' input.

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

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

The description is appropriately sized for a 13-parameter tool and is strongly front-loaded with purpose and exclusions. Bulleted sections keep it scannable, and the trigger phrases aid retrieval without replacing the core semantics.

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

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

Given no annotations, no output schema, and 13 optional parameters, the description is largely complete: it covers purpose, exclusions, return fields, and workflow. It still omits permission/authentication context and has the 'next_offset' versus 'offset' naming inconsistency.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters. The description adds useful workflow guidance for status, table, and type filters, but it does not explain most parameters and introduces a minor mismatch by referencing 'next_offset' instead of the schema's 'offset'.

Input schemas describe structure but not intent. Descriptions should explain 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 RawTree insert/query/describe/explain activity. It explicitly distinguishes itself from application/infrastructure log reading, so an agent can route 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?

Provides explicit when-to-use bullets, a suggested workflow, and a clear NOT-for section. It names concrete scenarios such as failed inserts, agent/CLI/API/UI verification, and filtering by table.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable specifics: the return fields (user IDs, emails, roles, creation times), the exclusion of pending invitations, and the auth requirement of user credential plus org membership. It doesn't cover pagination or rate limits, keeping it below a 5.

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

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

Well front-loaded with Purpose, Returns, Auth, and When to use sections. The markdown structure is clear, scannable, and every sentence contributes information with no redundancy.

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

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

For a single-parameter read-only list tool, the description covers purpose, return shape, auth requirements, and usage scenarios. Combined with annotations covering the safety profile and a fully documented schema, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents 'organization' fully. The description adds no syntax or format details beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (accepted members of a RawTree organization), and explicitly scopes out pending invitations. This distinguishes it clearly from siblings like add-organization-member or remove-organization-member.

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

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

The 'When to use' section provides two concrete scenarios: needing a member user ID before role changes or removals, and inspecting organization membership. This routes the agent away from mutation siblings and toward the correct read 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?

With no annotations, the description carries the behavioral burden and does add real value: it discloses the return shape (names, roles, plans, avatar URLs) and a genuine auth pitfall (needs a user credential, database API keys cannot list organizations). It omits pagination or rate-limit behavior, so it's 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?

Purpose is front-loaded, then returns, auth, and usage are cleanly delineated with bold headers and bullets. Each section adds needed information and nothing is redundant.

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

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

For a parameterless read tool with no output schema and no annotations, the description supplies everything required: what comes back, how to authenticate, and when to reach for it. Nothing essential is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-parameter schema is 4.

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

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

States a specific verb (List) and resource (RawTree organizations) scoped to 'available to the authenticated user,' so an agent knows exactly what comes back. It does not explicitly contrast itself with neighbors like list-organization-members, but the resource is unambiguous.

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

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

A dedicated 'When to use' block gives two concrete triggers (need an org name before listing clusters; working across multiple orgs in one connection). It stops short of naming an alternative tool or an explicit when-not, so it's clear context rather than full routing guidance.

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

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

With no annotations, the description carries the full burden, and it does disclose the return payload (tables with row/byte counts plus database and organization context), which is real behavioral context. It stops short of stating auth requirements, pagination, or behavior on a missing/ambiguous database, leaving those gaps.

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

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

Front-loaded purpose statement, then compact labelled sections (NOT for / Returns / When to use). Every sentence carries routing or scope information with no filler; the header scaffolding aids scanning rather than padding.

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

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

For a read-only list tool with no output schema and no annotations, the description supplies what the returns look like and how it differs from siblings. It is nearly complete; only edge-case behavior (empty database, permission failures) is unaddressed, which is minor for this tool class.

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

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

Schema coverage is 100%, so the schema already documents cluster, database, and organization, including which is optional. The description references database and organization context but adds no syntax, format, or defaulting detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource (list tables in a RawTree database) and immediately scopes what it returns (row and byte counts). It explicitly distinguishes itself from siblings run-query and describe-table, so an agent can route correctly 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?

The 'NOT for' section names alternatives (run-query for data, describe-table for columns) with the condition that selects them, and the 'When to use' bullets give three concrete triggering scenarios. Both when-to-use and when-not-to-use are explicit.

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

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

Goes well beyond the annotations (destructiveHint=true, readOnlyHint=false) by disclosing that pausing is asynchronous, that databases become unavailable until resumed, and that an org-admin access token is required. The async behavior and availability impact are exactly the kind of traits annotations cannot convey.

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

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

Sectioned into Purpose/Returns/Auth/Safety with the core action front-loaded, so an agent can skim efficiently. The bold headers are slightly heavy for the amount of content, but no sentence is 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 still explains the return value (the updated cluster and its lifecycle status), plus auth requirements, async timing, and safety consequences. Nothing an agent needs to invoke this mutation 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 both parameters are documented in the schema, so the description's brief mention of organization and cluster ID adds little. Baseline 3 applies when the schema carries 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 and resource ('Request that a RawTree dedicated cluster pause') with the target object named precisely. An agent can distinguish this from sibling mutations like resume-cluster, update-cluster, or delete-cluster 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 a follow-up path ('Use get-cluster to check one cluster's progress') and a precondition (confirm org and cluster ID), but does not compare against alternatives such as resume-cluster or state when pausing is the right action versus other lifecycle operations. Usage is implied rather than explained.

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 destructiveHint=true and readOnlyHint=false; the description goes well beyond them by disclosing the authorization model (organization admin, enforced by the API), a server-side guard (RawTree prevents removing the last organization admin), and a required confirmation workflow. This is exactly the extra context a destructive mutation 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?

Bold-labeled sections (Purpose/Returns/NOT for/Auth/Safety) front-load the action, then the exclusions, then the risk. Four short paragraphs, each carrying distinct information 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?

With no output schema, the description compensates by stating the return ('Whether the member was removed'). Auth, safety, alternatives, and prerequisites are all covered for a 2-parameter destructive tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that userId must belong to an *accepted* member (not a pending invite) and that organization is the container being affected. That constraint affects which value is valid and is not fully captured by the schema's terse descriptions.

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

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

States a specific verb and resource ('Remove an accepted member from a RawTree organization') plus the effect ('revoke their organization access'). It explicitly distinguishes itself from the sibling list-organization-members and from invitation revocation, so an agent can route correctly without opening any schema.

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

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

Gives an explicit exclusion ('NOT for: Revoking a pending invitation') and names the prerequisite tool (list-organization-members) needed to obtain the user ID. It also states the required credential level and a mandatory user-confirmation step, leaving no inference to the agent.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, signaling a mutating operation. The description adds important context beyond annotations: that resuming is asynchronous, it returns the updated cluster, and that the RawTree API requires an organization admin token. These details help the agent understand side effects and required permissions.

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

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

The description is well-structured with bolded sections (Purpose, Returns, Auth, Safety) and is front-loaded with the core action. It is slightly verbose in the Safety section, but each sentence contributes useful information.

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

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

Given the complexity of a mutation tool and the lack of an output schema, the description covers the essential aspects: purpose, asynchronous behavior, return value, authorization requirements, and a safety warning. It is nearly complete, though it could mention error conditions or rate limits.

Complex tools with many parameters or behaviors need more documentation. 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 input schema already fully documents the two parameters (organization and clusterId). The description does not add any new semantic details about parameter formatting or constraints. Baseline 3 is appropriate 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?

The description states a specific action (resume) for a specific resource (paused RawTree dedicated cluster), clearly distinguishing it from the sibling pause-cluster. It names the required precondition ('paused') so the agent knows the tool only applies to paused clusters.

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

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

The description explicitly says to use get-cluster to check progress after resuming, and implies the tool is for paused clusters. It does not explicitly state when NOT to use it (e.g., for running clusters) or list alternatives like pause-cluster, but the context is sufficiently clear from the 'paused' precondition.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavior: queries are validated as read-only and unsafe statements are rejected, and it specifies the response components (meta, data, rows, statistics, hints) plus guidance to bound exploratory queries. It does not cover auth/permissions or rate limits, 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?

The markdown headers (Purpose, NOT for, Returns, When to use, Workflow) front-load the essentials and are easy to scan. There is mild redundancy between the 'When to use' bullets and the 'Key trigger phrases' list, but overall it is tight for the amount of useful content.

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

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

With no output schema, the description must explain return values, and it does so explicitly (meta, data, rows, statistics, hints). Combined with purpose, exclusions, and workflow guidance, it gives an agent everything needed to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the optional database override and cluster/organization. The description only reinforces the bounded-SELECT advice and adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Execute a read-only SQL query against a RawTree database') and enumerates the return shape (JSON rows, column metadata, statistics, hints). It explicitly separates itself from mutating siblings via the 'NOT for: Inserting, updating, deleting' clause, so an agent can distinguish it from insert-json/insert-from-url 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?

Provides an explicit 'When to use' list plus a 'NOT for' exclusion and a workflow recommendation (start bounded, add LIMIT and order by a time column). It states both when to use and when not, leaving little to inference, though it names the exclusion by action rather than by sibling tool name.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds substantial context: paused removes the connector from active runtime, active restores consumer groups with Kafka offset semantics (retention, at-least-once), auth requires org-admin, and pausing interrupts ingestion until resumed. This goes well beyond the structured annotations.

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

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

Well-structured with bold headers and front-loaded purpose. Every sentence earns its place: behavior, auth, and safety each add distinct operational context. No wasted words.

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

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

Complete for a mutation tool with destructive annotations: purpose, behavior, auth, and safety are covered. The lack of output schema means return values could be mentioned, but for a status setter this is a minor gap.

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

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

Schema coverage is 75% (cluster, connectorId, organization have descriptions). The description explains the enum values for the status parameter—what 'paused' and 'active' do—adding meaning the schema lacks. It also reinforces required parameters via the safety note, though it does not add format/syntax details for the other parameters.

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

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

States a specific verb (pause/resume) and resource (every destination in one connector). No sibling tool performs the same connector-level status action; cluster pause/resume is clearly distinct by name and description. An agent can select it without opening the schema.

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

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

Implies usage through the purpose and safety note, but offers no explicit when-to-use vs alternatives or when-not-to-use. The safety instruction to confirm parameters adds practical guidance but is not a usage condition. No comparison to pause-cluster/resume-cluster or other connector tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description goes further by clarifying that uninstall removes installation state but does NOT delete stored data, that native endpoints become unavailable, and that org-admin credentials are required – exactly the kind of beyond-annotation context that matters for a destructive operation.

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

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

Front-loaded with labeled sections (Purpose, Returns, Behavior, Auth, Safety) that let an agent scan the operative facts quickly. Every section carries information the agent needs, including return values that are otherwise unavailable since no output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, 3-required-param mutation with no output schema, the description covers purpose, return shape, data-retention behavior, auth requirements, and a confirmation safeguard. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents organization, cluster, and appId (including provenance from list-apps/list-clusters). The description's mention of the three identifiers adds confirmation guidance but no new syntax or format detail, 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 precise verb+resource: uninstall a RawTree app from one cluster and disable its native endpoints. This is clearly distinguished from the sibling install-app and from cluster-level tools like pause-cluster.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 precondition – the user must confirm organization, cluster, and app ID before calling – which implies the context of use. It stops short of explicitly contrasting with alternatives or stating when-not-to-use (e.g., pausing vs uninstalling).

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=false and idempotent=true, but the description adds substantial context beyond them: the auto-pause semantics (inactivity threshold), the supported range, the org-admin token requirement, and a mandatory user-confirmation safety step. It could say more about what happens to an already-paused cluster, but coverage is strong.

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

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

Bolded, front-loaded sections (Purpose, Returns, Behavior, Auth, Safety) make it scannable, and every line carries actionable content 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?

With no output schema, the description usefully explains the return value ('the updated cluster, including its effective idle timeout'), and it covers auth and safety. Complete enough for a 3-param mutation tool, though return details are brief.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it clarifies that 0 disables idling and that the effective supported range is 15-43200 minutes, which refines the raw 0-43200 min/max in the schema.

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

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

The description states a specific verb and resource: 'Update the idle timeout for a RawTree dedicated cluster.' It is tightly scoped to a single field, which differentiates it from siblings like pause-cluster/resume-cluster, though it doesn't name those alternatives explicitly.

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

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

It explains how to use idleTimeoutMinutes (0 disables idling; 15-43200 supported), which implies intended usage, but it never states when to reach for this tool versus pause-cluster, resume-cluster, or create-cluster. Alternatives are left to inference.

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

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

Annotations already mark this as a non-read-only, destructive operation. The description adds meaningful behavioral context beyond annotations: admin auth is required, RawTree prevents demoting the last admin, and user confirmation is mandated before calling.

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

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

The description is front-loaded and organized into Purpose, Returns, NOT for, Auth, and Safety sections. Every sentence carries useful information for correct invocation, 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?

Given the schema, annotations, and absence of an output schema, the description is complete: it covers the operation, exclusions, return value, authorization, last-admin guard, and safety confirmation 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%, so the input schema already documents user ID source, organization, and role enum. The description largely repeats that the role is admin or member and does not add syntax or format details beyond the structured fields.

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

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

The description states a specific verb and resource: 'Change an accepted organization member's role to admin or member.' It also distinguishes the target scope from pending invitations, so an agent can tell it apart from invite-handling siblings.

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

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

Explicitly says NOT for pending invitations and directs to list-organization-members to identify an accepted member. This gives both when-not guidance and the correct alternative tool, leaving little ambiguity.

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?

Despite annotations covering non-read-only and idempotency, the description adds rich value: it explains the assume-role flow, that it writes/reads/deletes a probe object under each path, the region constraint, and that it is safe to retry. It explicitly warns the probe writes to and deletes from both destinations and notes IAM propagation delays, which annotations cannot convey.

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

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

Well front-loaded with bolded section headers (Purpose, Returns, Behavior, Auth, When to use, Safety, Reliability) that make it scannable. It is somewhat long, but each section earns its place for a mutating verification tool with nested parameters and no output schema.

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

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

For a 2-param mutation tool with nested objects, no output schema, and 100% schema coverage, the description supplies the missing return summary, auth requirements, ordering relative to create-cluster, region constraint, safety warnings, and retry behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema documents organization, s3Storage, data/backups, roleArn, and externalId. The description adds behavioral meaning (paths default to bucket root, externalId must exactly match the trust policy, region constraint) but does not extend schema syntax beyond structured fields. Baseline 3 is appropriate.

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

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

The description states a specific verb (verify), resource (cluster S3 access via a customer IAM role), and scope (before cluster creation). It is clearly distinguishable from the sibling verify-database-s3-access and create-cluster by naming cluster/S3/storage context explicitly.

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

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

It gives explicit when-to-use ('after the IAM trust and permissions policies are configured and immediately before create-cluster whenever its optional s3Storage field will be provided') and when-not ('unnecessary when RawTree-managed storage will be used'), 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?

Goes well beyond the annotations: it discloses the exact assume-role flow, the write/read/delete probe object behavior, that both buckets must share the cluster region, the destructive-in-practice temporary write, the externalId trust-policy matching requirement, org-admin auth, and retry safety with IAM propagation delay. This is consistent with idempotentHint=true, destructiveHint=false, and readOnlyHint=false.

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

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

Bold-labeled sections (Purpose, Returns, Behavior, Safety, Auth, Reliability) front-load the essential facts, and every sentence carries decision-relevant content without padding.

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

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

Despite no output schema, the description states the return shape ('whether access was verified and a human-readable result message') and covers behavior, safety, auth, and retry semantics for a 4-parameter nested-object tool. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: paths are optional and default to the bucket root, both configured buckets must be in the cluster environment's AWS region, and externalId must exactly match the IAM trust policy value.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Verify that RawTree can use a customer IAM role to access customer-owned S3 storage') and scopes it temporally ('before creating a database'), which separates it from the sibling verify-cluster-s3-access.

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

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

Clearly frames the context ('before creating a database') and lists the exact inputs to confirm first, giving strong usage guidance. It never explicitly names verify-cluster-s3-access or states when *not* to use this tool, so it stops short of full routing guidance.

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