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?

No annotations exist, so the description carries the full burden and does: it discloses the one-time visibility of the key value, the returns shape (key value + expires_at, null meaning never), the auth requirement (POST /v1/keys, admin permission), and the immutability of expiration. These are exactly the non-obvious traits an agent needs before invoking.

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

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

Front-loaded purpose, then exclusions, returns, auth, and use cases — every block earns its place. The heavy markdown sectioning is slightly more scaffolding than the content requires, keeping it off a 5.

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

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

With no output schema, the description supplies the return contract itself (key value shown once, expires_at semantics), plus auth and failure-relevant constraints. Enough for an agent to call and then handle the result 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 all six parameters are already documented; the description only nudges on the permission enum ('prefer read_only for query-only agents'). That is additive but thin, so the baseline 3 is right.

Input schemas describe structure but not intent. Descriptions should explain 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 scopes it to a cluster. The 'NOT for: User login' line plus sibling names (list-api-keys, delete-api-key) make it trivially distinguishable from adjacent tools.

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

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

Provides an explicit exclusion ('NOT for user login — use RawTree auth/CLI or the dashboard') and three concrete when-to-use scenarios (CI/agents/scripts, permission tier selection, rotation-before-revoke). Nothing about the decision 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 declare write/non-idempotent/non-destructive; the description goes far beyond that by disclosing asynchronous provisioning after acceptance, fixed replica count with vertical autoscaling between minimumSize and maximumSize, required admin token, non-idempotency with a retry-reconciliation protocol, and specific safety warnings (single-replica no redundancy, verification invalidation on identity change). This is exactly the behavioral 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?

The labeled sections (Purpose/Returns/Behavior/Auth/Safety/Reliability) front-load the essentials and each section carries distinct, decision-relevant content. It is long and occasionally restates schema facts (paths optional, required s3Storage children), which costs a point, but the length is justified by a 9-parameter provisioning tool with a multi-step prerequisite chain.

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

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

No output schema exists, and the description compensates by describing the return payload (ID, lifecycle status, initial resources) and the async follow-up path. Auth, safety workflow, identity generation, and failure reconciliation are all covered — an agent has everything required to invoke this 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 coverage is 100%, so the schema baseline is already satisfied; the description still adds real meaning beyond it — when to omit s3Storage, the externalId generation rule vs the requirement for custom storage, the required-vs-optional split inside s3Storage, and the resourceTag tagging convention for buckets and roles. It stops short of enumerating every field, but the added semantics are substantive.

Input schemas describe structure but not intent. Descriptions should explain 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 ("Provision a new RawTree dedicated cluster in an organization") and is clearly distinguishable from siblings like update-cluster, get-cluster and create-database. An agent knows exactly what this does without opening the schema.

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

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

Explicitly names prerequisites and sequencing (list-regions → list-cluster-sizes → verify-cluster-s3-access → create-cluster), names the alternatives for progress checking (get-cluster) and reconciliation (list-clusters), and specifies when s3Storage should be supplied vs omitted. Nothing about when to use this path 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?

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 cover readOnly/idempotent/destructive, but the description goes well beyond them: org-admin auth requirement, non-idempotency, the reconciliation procedure on ambiguous responses, the External ID reuse rule and identity-override prohibition, and the inheritance behavior of s3Storage on all tables. This is substantive context not derivable from structured fields.

Agents need to know what a tool does to the 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) make it skimmable and front-loaded, with no filler sentences. It is on the longer side, and the Returns line is largely superseded by the schema, but every other sentence carries decision-relevant information.

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

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

For a non-idempotent mutation with a nested s3Storage object and no output schema, the definition still covers auth, failure recovery, optionality, and the verify-then-create prerequisite. Nothing an agent needs in order to call 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 coverage is 100%, so the baseline is 3; the description still adds meaning by explaining that s3Storage is optional, defaults to cluster storage, and that its contents are inherited by all tables in the database, plus which inner fields are required. It stops short of describing path/prefix semantics, which the schema already handles.

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

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

States a specific verb+resource ('Create a database') scoped to an organization and cluster, which cleanly separates it from create-cluster, create-table, and delete-database among the siblings. An agent needs no further reading to know what this tool produces.

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

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

Gives explicit preconditions and ordering: call list-databases and confirm org/cluster/name with the user first, and call verify-database-s3-access with an identical configuration before supplying s3Storage. It also states an exclusion — never reuse a verification after changing any s3Storage field — which is exactly the disambiguation an agent needs.

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=false, but the description adds genuinely non-obvious context: 'Saving does not fetch keys' (a side effect an agent would otherwise assume), the auth modes required, and the shape of the returned issuer object. Remaining gaps are duplicate-name behavior and whether issuer_url is validated against live discovery, which the agent must discover by trial.

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

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

Four short sentences in a deliberate order: what it creates, the key non-obvious side effect, the return value, then the authorization gate. Nothing is repeated and nothing could be dropped without losing information the agent needs.

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

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

For a six-parameter creation tool with no output schema, the description covers the important bases: creation modes, the no-key-fetch caveat, the returned fields, and the auth constraint. It stops short of describing what happens on a duplicate issuer name or whether jwks_url is verified at save time, which matters for an operation annotated as destructive and non-idempotent.

Complex tools with many parameters or behaviors need more documentation. 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%, and the description compensates only partially: it explains the discovery-vs-explicit-JWKS dichotomy that governs jwks_url/jwks_source, but leaves 'organization' ambiguous (ID vs. slug) and says nothing about the 'name' slug pattern or the free-form 'description'. The mode relationship is the useful addition beyond the schema's own parameter 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?

The description opens with a specific verb and resource ('Create an organization issuer') and immediately scopes it to the two supported modes (discovery vs. explicit JWKS URL). The verb alone separates it from the get/list/update/delete-federation-issuer siblings, and the 'organization issuer' phrasing separates it from create-federation-rule.

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

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

It states the precondition clearly (organization admin via user session or OAuth with full_access) and adds an explicit exclusion ('API keys and workload tokens cannot manage federation configuration'), which tells the agent when the call will fail. What it does not do is route between this and its siblings, e.g. that update-federation-issuer should be used for existing issuers.

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

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

Goes well beyond the annotations by naming the security consequence (the rule grants access and permits authentication), the exact return payload and its fields, and concrete authorization constraints: org admin, user session or OAuth with full_access, and an explicit exclusion for API keys and workload tokens. That exclusion is precisely the kind of failure mode an agent cannot derive from readOnlyHint/destructiveHint/idempotentHint.

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

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

Four short sentences ordered by importance: what it does, its effect, what it returns, then who may call it. No filler and no repetition of schema constraints.

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

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

Auth requirements and return shape are covered well and the absence of an output schema is mitigated by the explicit return description. However, for a 13-parameter privileged-creation tool with a nested claim_conditions object, the description gives no guidance on how to obtain an issuer_id or principal_id, or what claim_conditions keys are valid, leaving required-parameter construction under-specified.

Complex tools with many parameters or behaviors need more documentation. 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 only 23% across 13 parameters (10 required), and the description supplies almost nothing to compensate. The phrase about mapping an external identity loosely gestures at issuer_id/claim_conditions/principal_type, but claim_conditions structure, allowed_audiences, database_roles, permission, name pattern, and the non-inherited database default are all left undocumented.

Input schemas describe structure but not intent. Descriptions should explain 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 cluster rule") plus the core effect ("mapping an external identity to your user or a service account"), which is far more informative than the title. It stops short of explicitly contrasting itself with update-federation-rule or create-federation-issuer, so an agent must infer the boundary from the name alone.

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

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

Usage is implied by "An enabled rule permits authentication and grants the configured access," which hints this is the setup step before token exchange works. There is no explicit when-to-use/when-not guidance and no pointer to update-federation-rule for modifying an existing rule, so routing between the federation CRUD siblings 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses authorization requirements, an explicit auth-method exclusion, the fact that no credentials are minted, the separation of role from API key permissions, and a hard quota of 100 service accounts. These are exactly the behavioral traits an agent cannot infer from 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?

Sentences are dense and front-loaded, leading with the action and constraint before auth and quota details. The one small redundancy is restating that API key permissions are configured separately, which the role parameter description already says.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 no output schema, the description still states the returned fields, the auth model, the credential-free nature of the result, and the account quota. An agent has everything needed to decide whether to call it and what to expect.

Complex tools with many parameters or behaviors need more documentation. 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 (name pattern, role enum, description length, organization source) are already fully documented in the schema. The description echoes the immutability of the name and the stored-role distinction but adds no new syntax or format meaning, so the baseline of 3 applies.

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

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

The first sentence gives a specific verb and resource ("Create an organization service account") plus a key constraint ("immutable, unique name"). It also implies the distinction from create-api-key by saying "This creates an identity without credentials," though it never names that sibling explicitly.

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

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

Clear preconditions are given: an organization admin, a user session or OAuth, and the exclusion of API keys as a management path. It does not explicitly say when to prefer create-api-key over this tool, but "API key permissions are configured separately" points the agent in that direction.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing storage resolution (database storage if configured, otherwise cluster default, never per-table), stating that the auth requirement is organization admin, and giving explicit ambiguous-response recovery via list-tables. That 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?

Uses front-loaded bold headers (Purpose, Returns, Behavior, Sorting key, Auth, Reliability) so an agent can scan to the relevant section. Each section carries information an agent needs when calling the tool, including the Returns section, which compensates for the missing output schema, and there is no filler.

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

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

For a 5-parameter creation tool with no output schema, the definition covers what is created, what is returned, how storage is resolved, how the sorting key is chosen and later changed, the auth level required, and how to recover from an ambiguous response. 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 coverage is 100%, so the baseline is 3, but the description adds real meaning to sortingKey: the comma-separated SQL expression format, ordering with lowest cardinality first, and the omit-vs-set trade-off. It also clarifies that the storage relationship is between the cluster and the database, not per table. It adds nothing beyond the schema for name, organization, and cluster.

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

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

States a specific verb and resource with scope: 'Create an empty RawTree table in a database.' That is unambiguous against siblings like create-database, create-cluster, and create-connector, which target different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 conditional guidance for the optional sortingKey (omit for exploratory tables, set when the query pattern is known) and routes to a named sibling: 'Use update-table to change it later.' It also gives a recovery path via list-tables. It does not say when not to create a table (for example, when one already exists), so it falls short of a full 5.

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

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

Annotations already flag non-idempotent and destructive, but the description goes well beyond them: it explains that an enabled schedule starts recurring execution and sink delivery, that workflows run with organization credentials and survive revocation of the creating key, and that write capability comes from INSERT SELECT in the SQL. It also states the authorization model (admin API key bound to org and cluster, or OAuth; members read, admins write), which is behavior an agent cannot infer from the annotations.

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

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

Front-loaded with purpose, defaults, and the non-idempotency warning before drifting into detail. The long trailing block enumerating returned fields is verbose, but it is the only place that information exists since there is no output schema, so it largely 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 7-parameter nested-object mutation with no output schema, the description covers side effects, defaults, auth prerequisites, permission boundaries, non-idempotency recovery, and the full return shape including the security-relevant note that header values and some URLs are never returned. An agent has everything needed to call this 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 coverage is 71%, so the schema already documents most parameters; the description still adds meaning by stating the concrete defaults (cron "* * * * * *" enabled, sinks=[]), the semantics of schedule=null, and the rule that each Slack sink must use a distinct integration and channel with IDs assigned by the API. Those constraints appear nowhere 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?

Opens with a specific verb and resource: "Create a scheduled SQL workflow." That is unambiguously distinguishable from update-workflow, get-workflow, list-workflows, and delete-workflow in the sibling list, and the rest of the opening sentence scope (scheduled SQL execution) narrows it further.

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

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

Gives concrete selection context: use schedule.enabled=false to create paused, schedule=null for manual-only, and reconcile an uncertain result with list-workflows before retrying. It also names list-integrations and list-slack-channels as prerequisite lookups. It never explicitly says when to choose update-workflow instead of create, which keeps 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 annotations (destructive, idempotent), the description discloses the 409 conflict condition, the null return on success, the required role (organization admin), and which credential types are rejected (API keys, workload tokens). These are operative facts an agent cannot get from the structured fields.

Agents need to know what a tool does to the 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 tight sentences ordered action → precondition → return → authorization, with zero filler. Every sentence conveys a distinct operational fact and the most decision-relevant content is front-loaded.

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

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

For a destructive, two-parameter tool with no output schema, the description covers error behavior, return value, and auth constraints well. The remaining gap is parameter meaning, which is undocumented in both the schema and the description.

Complex tools with many parameters or behaviors need more documentation. 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 0% for two required parameters, so the description carries the full burden and fails to compensate. It never explains what 'id' refers to (issuer UUID) or what 'organization' expects (slug vs. identifier), leaving both parameters semantically opaque.

Input schemas describe structure but not intent. Descriptions should explain 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 and resource ("Delete the issuer"), which is unambiguous against siblings like create-federation-issuer and update-federation-issuer. It doesn't explicitly name the related sibling delete-federation-rule as the alternative, so it falls just short of a 5.

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

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

It gives a concrete precondition for use: referencing rules must be deleted first or the API returns 409, which strongly implies delete-federation-rule is the prior step. It also states the auth contexts in which the call is valid. It does not explicitly say when not to use this tool versus update/get 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?

Goes beyond the destructiveHint/idempotentHint annotations by disclosing the actual side effect (workload access through the rule is revoked), the return contract ('Returns null on success'), and the authentication requirements with explicit credential exclusions. These are exactly the operational details 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?

Three tight sentences, each carrying distinct load: effect, return value, then authorization constraints. The destructive consequence is front-loaded, so an agent reading only the first clause still knows this is a destructive operation.

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

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

For a simple destructive delete with no output schema, the description covers effect, return value, and auth, which is most of what an agent needs. The remaining gap is parameter-level clarity, since three required undocumented params are never explained and error behavior for a missing rule is 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?

All three parameters (organization, cluster, id) have 0% schema description coverage, and the description never mentions any of them. It does not clarify that id is a rule UUID, whether organization/cluster are names or identifiers, or what happens if the id does not match an existing rule in that scope.

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

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

States a specific verb and resource ('Delete the rule') and adds the consequence ('revoke workload access through it'), which tells an agent exactly what operation this is. It relies on the tool name to establish that 'the rule' is a federation rule, and it does not explicitly contrast with update-federation-rule, but the verb alone separates it from the other federation 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?

Gives concrete preconditions and exclusions: organization admin, user session or OAuth with full_access, and explicitly rules out API keys and workload tokens. What's missing is guidance on alternatives — e.g., whether update-federation-rule should be preferred when the goal is only to suspend access temporarily rather than revoke 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 destructiveHint=true and idempotentHint=true already declared, the description still adds real value: the exact destruction boundary (definition only, no data), the authentication constraint (API keys unsupported), and the success return shape. What it omits is the behavior on a missing or non-owned id, which matters given the idempotent hint.

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

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

Four short sentences, each carrying distinct information: action, auth requirement, blast radius, and return value. The action and scope are front-loaded with no filler.

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

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

Covers auth, destruction scope, and the return value even though no output schema exists. The one gap is failure semantics for a nonexistent or unowned query id, which an agent needs given the idempotency declaration.

Complex tools with many parameters or behaviors need more documentation. 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, establishing a baseline of 3. The description adds only the ownership qualifier on id and says nothing about the cluster/organization parameters beyond what the schema states.

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

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

States a specific verb and resource ('Delete a saved query') plus an ownership scope ('you own') and the identifier basis ('by its id'). This clearly separates it from sibling deletions such as delete-table, delete-database, delete-workflow, and delete-api-key.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 sets the boundary 'Deletes only the saved definition and does not execute SQL or delete underlying data,' which effectively tells the agent when this is the wrong tool (data/SQL deletion). It also states the auth context (session/OAuth, not API keys). It does not point at list-saved-queries as the way to obtain an id, so it stops short of full alternative routing.

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

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

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?

Goes well beyond the annotations by disclosing non-reversibility scope ("does not undo previous SQL writes or completed deliveries"), the exact success shape ({ id, deleted: true }) and the fact it is only returned after API confirmation, plus credential binding and workflow execution semantics. This is the kind of 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?

Purpose and irreversibility caveat are front-loaded, and the return-value contract is placed well. The final sentence about workflows running under organization credentials and surviving key revocation is tangential to performing a delete, so a sentence does not fully earn 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 present, the description supplies the return contract itself, along with side effects, authorization prerequisites, and scope limits. For a three-parameter destructive tool this covers everything an agent needs before invoking.

Complex tools with many parameters or behaviors need more documentation. 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 id, cluster, and organization; baseline 3 applies. The description adds a small amount by implying why organization and cluster are required (the admin key must be bound to them), but it adds no syntax, format, or ID-sourcing detail beyond the schema.

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

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

States a specific verb and resource ("Delete a workflow definition and its schedule") plus the operational consequence ("stopping future evaluations"), which cleanly separates it from delete-saved-query, delete-table, and the sibling workflow tools (get-workflow, update-workflow). An agent needs no schema lookups to know what this removes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 authorization context (admin API key bound to the org/cluster, or OAuth) and the role model, which tells the agent when the call is permitted. It does not explicitly say what to use instead when the intent is to temporarily stop evaluations (e.g., update-workflow) rather than remove the definition, so there is no exclusion guidance.

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

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

With no annotations, the description carries the behavioral burden itself and does disclose the return shape, including the non-obvious semantics of sorting_key (comma-separated SQL expression, empty when keyed per part from ingested data). It does not state side-effect freedom explicitly, nor permission/auth requirements or behavior when the table doesn't exist, so it stops short of full disclosure.

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

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

Bold-labeled sections front-load purpose, exclusion, and return shape before the usage list, and each line contributes distinct information. No filler sentences; the length is proportionate to a four-parameter metadata tool.

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

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

With no output schema and no annotations, the description covers purpose, anti-purpose, return contents, and trigger scenarios — enough to call it correctly. It leaves out error behavior (nonexistent table, dynamic-schema edge cases) and any auth/permission notes, which keeps it short of a 5.

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

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

Schema description coverage is 100% with four well-documented parameters, so the schema already does the work and baseline 3 applies. The description only glosses the table name implicitly and does not explain cluster/database/organization precedence, which is where added value would have been possible.

Input schemas describe structure but not intent. Descriptions should explain 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") against a specific resource (a table's columns, row count, byte count, sorting key, database, organization), and explicitly excludes the closest sibling behavior by naming run-query for row sampling. An agent can distinguish this from run-query, list-tables, update-table, and create-table 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 with the alternative (run-query for SELECT), plus four concrete trigger conditions (before writing SQL, after a column-not-found failure, after insert to inspect dynamic schema, before changing the sorting key). Both the when and the when-not are present, which is the top of the scale.

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, and the description adds real value beyond that: the auth requirement (user access token plus organization membership), the guarantee that role ARNs and secrets are never returned, and the null semantics for older clusters lacking saved identity. It does not cover error behavior, such as what happens when the cluster ID is unknown or outside the organization.

Agents need to know what a tool does to the 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, returns, auth, and usage in a scannable order with no filler sentences. The Returns paragraph is dense and long, but each clause describes a distinct field the caller must interpret.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 carries the return-shape burden and does so thoroughly, including the nested s3_storage data/backups structure and the empty-path-means-bucket-root convention. Auth preconditions and the single-cluster scope are both stated, leaving nothing an agent needs before calling.

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

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

Schema description coverage is 100%, with both parameters documented in-schema (clusterId sourced from list-clusters, organization as the containing scope). The description adds no further 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 ("Get one RawTree dedicated cluster and its current lifecycle status") and implicitly contrasts with the bulk listing operation. An agent can distinguish it from list-clusters and update-cluster 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?

A dedicated "When to use" block gives three concrete triggering conditions, including the post-pause/resume status check. The last bullet routes the agent away from the full-list alternative, though it describes that sibling by behavior rather than naming 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantial operational context: it requires an organization admin, a user session or OAuth with full_access, and explicitly excludes API keys and workload tokens. That access constraint is exactly the kind of behavior an agent cannot get from annotations.

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

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

Three sentences, front-loaded with purpose and return shape, then the access constraint. No filler or repetition; the only mild looseness is that the return-field sentence could be trimmed since there is no output schema to complement it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 enumerates the returned object's fields, and it covers the authentication prerequisites. The remaining gap is input semantics — for a two-parameter tool at 0% schema coverage, that missing piece keeps it from being fully self-sufficient.

Complex tools with many parameters or behaviors need more documentation. 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 0% for two required parameters, so the description must carry the burden — and it does not. It never explains what 'organization' expects (slug, name, or ID) or that 'id' is the issuer UUID, leaving both inputs effectively undefined beyond their JSON types.

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

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

The description names a specific action ('Read the saved configuration') and enumerates the returned fields (id, organization_id, created_at, updated_at), which makes clear this fetches a single federation issuer. It stops short of explicitly contrasting with list-federation-issuers, but the singular resource plus 'get-' naming makes the distinction workable.

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

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

Usage is only implied: 'read the saved configuration' suggests inspecting an existing issuer rather than listing or mutating. There is no explicit when-to-use/when-not statement or named alternative (e.g., 'use list-federation-issuers to enumerate'), so an agent must infer the selection between get- and list- siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the required role (organization admin), acceptable session types, and the explicit exclusion of API keys and workload tokens for federation configuration. It stops short of covering not-found behavior or errors.

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

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

Three short sentences, front-loaded with the operation and followed by return shape and access constraints, with no filler. The opening phrase 'Read the saved configuration' is slightly generic for a tool whose subject is a federation rule, but nothing is wasted.

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

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

With no output schema, describing the return object is valuable, and the auth constraints are covered. However, for a 3-required-parameter lookup tool it leaves the meaning of those identifiers undocumented and says nothing about behavior when the rule does not exist, so the definition is adequate but incomplete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but it only names returned fields rather than explaining what organization, cluster and id refer to (name vs slug vs UUID lookup) and how they scope the fetch. The one hint, that a rule object includes organization_id and cluster_id, is indirect at best.

Input schemas describe structure but not intent. Descriptions should explain 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 read operation and enumerates the returned rule object's fields (id, organization_id, cluster_id, created_at, updated_at), making the resource clear. It does not distinguish itself from close siblings such as get-federation-issuer or list-federation-rules, so an agent must rely on the tool name to tell them apart.

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

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

Usage is only implied by 'Read the saved configuration' plus the eligibility constraints (org admin, user session or OAuth full_access). It never states when to use this versus list-federation-rules or get-federation-issuer, and it gives no when-not-to-use guidance beyond the credential exclusions.

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 readOnlyHint/idempotentHint annotations, it discloses important behavioral details: schedule is null for manual-only workflows, next_run_at is null while paused, url is null when unreadable, and header values are never returned. It also explains that workflows execute with organization credentials and persist after the creating key is revoked, which materially shapes how an agent should treat this resource.

Agents need to know what a tool does to the 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 is front-loaded in the first sentence, followed by a dense but organized field-by-field breakdown of the return object. It is long, but nearly every clause conveys a distinct fact (null semantics, security redaction, permission model); some field enumeration could be deferred to an output schema that does not currently exist.

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

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

With no output schema, the description carries the full burden of describing the return shape, and it does so comprehensively for the workflow object, query, schedule, and the three sink setting variants. Permission and credential requirements are also covered, leaving little an agent needs to call it correctly.

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

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

Schema coverage is 100%, so id, cluster, and organization are already documented in the schema. The description reinforces that the organization and cluster must be the ones the credential is bound to, but adds no new syntax or constraints beyond that; baseline 3 applies when the schema carries the load.

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

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

The description opens with a specific verb and resource: 'Read a workflow and its current schedule configuration,' and immediately enumerates the returned fields. An agent can distinguish this singular read from list-workflows by the required 'id' parameter and the singular object return, though no sibling is named explicitly.

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

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

It states the credential prerequisites ('Requires an admin API key bound to the selected organization and cluster, or OAuth') and the read/write permission split between members and admins. It does not, however, explicitly route the agent away from list-workflows or create/update-workflow, leaving the choice to be inferred from the singular read semantics.

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, the description carries the full burden and does: it discloses the auth requirement (admin database API key), the underlying endpoint (GET /v1/keys), the exact returned fields, and the null-vs-UTC semantics of expires_at. This is exactly the context an agent needs before calling a credentialed read.

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

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

Header-labelled sections are front-loaded with Purpose and exclusions first, then returns/auth/usage. The returns enumeration is long but earns its place because there is 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?

No output schema exists, yet the description enumerates return fields, and it covers auth, endpoint, and exclusions. Nothing an agent needs in order 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 (cluster, organization) are documented in the schema, so the baseline is 3. The description adds no additional meaning about scoping or defaults for these 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+resource (list API keys for a RawTree cluster) and explicitly distinguishes itself from the sibling create-api-key and delete-api-key tools. 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?

Includes an explicit 'NOT for' block naming the alternatives, plus three concrete 'When to use' triggers (audit permissions, need key ID before revoking, inventory question). Both the positive and negative routing cases are covered.

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

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

Annotations already declare readOnlyHint=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 so: it enumerates the returned fields, discloses that role ARNs and secrets are never returned, warns that results can be a partial list with unavailable_regions and that five-second per-region lookups apply, and states which conditions still error. This is exactly the behavioral context an agent needs beyond structured fields.

Agents need to know what a tool does to the 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 / Auth / When to use) with purpose front-loaded make it scannable. It is on the long side and the nested s3_storage field walkthrough is dense, but since no output schema exists, that detail earns most of 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?

No output schema exists, and the description fully compensates by describing the return payload, null/empty-path semantics, partial-result behavior, and error conditions. Combined with the auth requirements, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema description coverage is 100% for the single `organization` parameter, so the schema already defines its meaning. The description reinforces the org-scoping constraint ("accessible in an organization") but adds no format or lookup guidance beyond that, making the baseline 3 correct.

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

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

States a specific verb and resource ("List RawTree dedicated clusters") plus the scope ("accessible in an organization"). Plural list scope makes it naturally distinct from get-cluster (single cluster), list-cluster-sizes and create-cluster without needing to name them.

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

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

The "When to use" block gives three concrete triggering conditions: existence questions, needing a cluster ID/lifecycle status, and inspecting resources before creating another cluster. It lacks explicit exclusions or sibling routing (e.g. "for one cluster's details use get-cluster"), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds genuine context beyond them: the auth requirement (OAuth user credential, API-enforced authorization) and the fact that values are backend-controlled and therefore may change. It does not cover caching or whether the catalog varies by region, which would have pushed it to 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 a bolded Purpose line, then Returns, Auth, and When-to-use in priority order — easy to scan. Slightly verbose with four labeled sections for a two-parameter read tool, 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?

A read-only catalog tool with no output schema needs its return shape and ordering constraint explained, and both are. The remaining gap is the undocumented 'organization' parameter and how the catalog differs per region, which an agent may need in a multi-tenant or multi-region call.

Complex tools with many parameters or behaviors need more documentation. 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 50% and the description says nothing about either parameter. regionId is self-documented in the schema, but 'organization' has no description anywhere, and the description does not explain the default-backend behavior for omitted regionId beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain 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 the current RawTree cluster creation options') and explicitly enumerates what the catalog contains (per-replica sizes, min/max replica counts, default autoscaling bounds). This clearly separates it from list-clusters, get-cluster, and list-regions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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, hard prerequisite: 'You MUST call this tool before create-cluster so replicas and both sizes come from the current backend-controlled catalog.' The alternative path (hardcoding values) is implicitly ruled out, which is exactly the routing information an agent needs.

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: the required organization-admin role, the acceptable credential types (user session or OAuth full_access), and the explicit exclusion of API keys and workload tokens.

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

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

Three short sentences, front-loaded with the action and return shape, followed by the access constraint. Nothing is padded, though the credential sentence runs slightly long relative to its value.

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

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

For a simple read-only list tool with no output schema, the description explains the return shape and auth requirements well. It still leaves gaps on the organization parameter semantics and on pagination or result-size behavior, which matter for a "list all" endpoint.

Complex tools with many parameters or behaviors need more documentation. 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 0% for the single required organization parameter, so the description carries the burden of explaining it and does not. It never says whether organization is a name, slug, or ID, nor that it scopes the listing to that org.

Input schemas describe structure but not intent. Descriptions should explain 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 and resource ("List all federation issuers") and adds the return shape ("array of complete objects with configuration, IDs and timestamps"). It does not explicitly distinguish itself from the sibling get-federation-issuer, though "List all" versus a singular get is reasonably implied.

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

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

Usage is implied by the list semantics and the tool is constrained by an organization parameter, but there is no explicit when-to-use guidance such as "use get-federation-issuer to fetch a single issuer" or "use list-federation-rules for its rules". The access restrictions given are auth preconditions rather than selection guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the admin/user-session/full_access OAuth requirement and the explicit exclusion of API keys and workload tokens. It does not add rate limits, pagination, or result-size behavior, so it sits above baseline but is not rich.

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

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

Three short sentences, front-loaded with the action and return shape, then the authorization constraints. Every sentence carries information; nothing is padding.

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

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

For a read-only list tool with no output schema, the description covers return shape and auth requirements adequately. However, the two required scoping parameters are left entirely unexplained, which is a meaningful gap given 0% schema description coverage.

Complex tools with many parameters or behaviors need more documentation. 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 0% and both required parameters, 'organization' and 'cluster', are undocumented in the schema, so the description should compensate but largely does not. It never explains that results are scoped by organization and cluster, and 'List all federation rules' arguably implies a global listing, which the required scoping parameters contradict.

Input schemas describe structure but not intent. Descriptions should explain 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 ('List all federation rules') and clarifies that complete objects with configuration, IDs and timestamps are returned. It does not differentiate itself from close siblings such as get-federation-rule or list-federation-issuers, but the core purpose 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?

There is no guidance on when to choose this tool over get-federation-rule, list-federation-issuers, or the create/update/delete rule siblings. The only context given is a prerequisite ('requires an organization admin'), which tells the agent about authorization, not about tool selection.

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

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

Beyond the read-only annotations, the description discloses authentication requirements (user OAuth and organization membership, no API keys), the exact return fields, the meaning of slack_available, and the settings_url fallback behavior. This is substantial operational context that an agent could not infer from 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?

The description is structured with clear Purpose, Returns, Behavior, Auth, and When to use sections, and it is front-loaded with the core purpose. It is somewhat long for a one-parameter list tool, but most of the detail is useful given the absence of an 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?

The tool has no output schema, but the description supplies the return shape, auth requirements, behavioral limitations, and usage scenarios. An agent has everything needed to call it correctly and interpret the response.

Complex tools with many parameters or behaviors need more documentation. 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% for the single organization parameter, so the schema already explains it adequately. The description adds that the organization must be one the user belongs to, but this is auth context rather than parameter-level meaning.

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

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

The description states a specific verb and resource: list integrations connected to a RawTree organization, with Slack workspaces as the concrete example. It is clear what the tool does, but it does not explicitly contrast itself with sibling tools such as list-slack-channels.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 two concrete scenarios, and the behavior section explains that connecting or disconnecting Slack cannot be done through MCP. This covers when to use and when not to use the tool, though it does not name direct alternative tools.

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

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

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?

Annotations already establish this as a safe read, and the description adds real behavioral context: only regions with a ready deployment are returned, with an exception for the legacy public default. That filtering behavior and the public/BYOC distinction are not derivable from 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?

Two sentences, front-loaded with the core purpose, then the actionable condition. No redundant restatement of the name or title.

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

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

With no output schema, the description usefully signals what comes back (regions with an enabled/ready state) and how to consume it. The only meaningful gap is the undocumented organization identifier format.

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

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

Schema description coverage is 0% for the single required `organization` parameter, so the description must carry the burden — but it only implies 'organization' conceptually and never says whether it expects an ID, slug, or name. The agent has no format guidance to construct a valid call.

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

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

States a specific verb and resource — listing public and BYOC regions accessible to an organization — which is well beyond tautology. It hints at adjacent siblings (cluster size and S3 checks, cluster creation) but never names them explicitly, so full sibling differentiation is only implicit.

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

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

'Use an enabled region ID for cluster creation and its prerequisite size and S3 checks' tells the agent what to do with the result and points downstream. It also sets a filtering condition (ready deployment required, except the legacy public default) but gives no explicit when-not or named alternative tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds real depth: there is no pagination, the exact response envelope and field set are given, and the visibility model is broken down per auth type (user sessions/OAuth vs read API keys vs write-only/database-role keys). This is disclosure 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?

Four sentences with the core action and return shape front-loaded, then access constraints, then the sibling hand-off. The field enumeration is long but earns its place because there is no output schema; only slight density keeps it off a 5.

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

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

With no output schema, the description supplies the return envelope and field list; with sparse annotations, it supplies the permission and pagination model. Nothing an agent needs in order to call this correctly, or to interpret the result, 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?

Both parameters (cluster, organization) are fully documented in the schema at 100% coverage, so the baseline is 3. The description only implies their meaning ('in a cluster', 'same organization and cluster') without adding format, default, or interaction detail beyond the schema.

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

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

The description opens with a specific verb and resource plus scope: list all saved SQL queries visible to you in a cluster, across databases. It also distinguishes itself from run-query by naming what the sibling does (execution) versus what this tool does (listing only).

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

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

It explicitly routes the agent to run-query for execution ('pass its sql and database to run-query with the same organization and cluster') and states what this tool does not do ('Listing does not execute SQL or grant access to the underlying data'). It also spells out which caller identities may use it and which auth modes are unsupported.

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

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

The annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds meaningful context beyond them: the admin requirement, the accepted auth mechanisms, and the explicit exclusion of API keys. It does not mention pagination or result-size limits, which is the remaining behavioral gap.

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

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

Two sentences, front-loaded with what the tool returns and followed by the access constraint. Nothing is redundant or padded.

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

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

For a one-parameter read tool with rich annotations and no output schema, the description is nearly sufficient: it describes return contents in lieu of an output schema and covers the auth prerequisite. Only pagination/result-count behavior is unaddressed.

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

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

There is a single parameter with 100% schema coverage whose description already explains it comes from list-organizations. The description only restates 'in an organization' and adds no format or sourcing detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('List service accounts in an organization') and enumerates the returned fields (IDs, names, descriptions, stored organization roles). It is clearly distinct from siblings like create-service-account and list-organization-members, though it never names an alternative 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?

Usage is only implied by the verb 'List'; there is no explicit when-to-use or when-not-to-use guidance relative to siblings. The one constraint given is real and useful, that the caller must be an org admin on a user session or OAuth and cannot use an API key, but that is a prerequisite rather than selection 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 readOnly/idempotent/non-destructive, yet the description adds substantially more: pagination mechanics, the counterintuitive case where a page returns zero channels but next_cursor is set because the search scan is bounded, and the prerequisite that the RawTree app must be a member of a private channel before posting. Auth constraints (user credential/OAuth required, API keys unsupported, RawTree-enforced authorization) are also disclosed, which no annotation 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 labels (Purpose, Returns, Behavior, Auth, When to use) make it skimmable and front-loaded, and the works-as-documented return shape is stated in one line. It is somewhat long and repeats name-substring matching from the schema, so a small amount of content doesn't earn 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 and four parameters, the description supplies the missing return contract ({ channels, next_cursor } with channel fields and null-cursor termination), the pagination loop the agent must implement, and the auth model. Nothing needed to call it correctly — including how to recover from an empty-but-cursored page — 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: cursor must be passed together with the same name used to produce it, and name matching ignores a leading '#', surrounding spaces, and case — normalization rules absent from the schema text. It stops short of a 5 because it doesn't discuss what organization/integration_id must be paired with (cross-org behavior).

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

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

Opens with a specific verb pair and resource: 'List or search the channels of a Slack workspace connected to a RawTree organization.' The scope (workspace of a connected org) and the two modes (list vs. search via name) are explicit, so an agent can distinguish this from siblings like list-integrations or get-workflow 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?

A dedicated 'When to use' block names both concrete triggers: finding a channel for a workflow Slack sink, and resolving a partially-described channel to an exact name or ID. It also pre-empts an alternative route by noting that Workflow Slack sinks accept channel_name directly, so the agent knows when this lookup is and isn't required.

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

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

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.