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

The description adds context beyond the annotations by explaining that caching stores data locally and that schedules are optional at creation time. Annotations only mark readOnlyHint and destructiveHint as false, so the description carries the burden of describing the mutation; it does so at a basic level. It does not disclose side effects such as whether creation triggers an initial refresh, how to monitor progress, or whether duplicate caches are handled, leaving some behavioral ambiguity.

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

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

The description is compact, front-loaded with the core purpose, and includes only relevant procedural guidance. The second paragraph about projectId is practical and not redundant with the schema. It loses one point because it somewhat repeats schedule details already present in the input schema, but overall it remains efficient.

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

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

The description covers the main action, the project selection workflow, and the schedule options, which is enough for a basic call. It omits guidance on discovering catalogId, schemaName, and tableName, even though sibling list tools exist, and it does not describe what the response will be or how to verify success. For a 4-required-parameter creation tool with no output schema, this leaves noticeable gaps.

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

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

Schema coverage is 50%, and the description adds some useful context for the schedule parameters by repeating ISO-8601 examples and noting they can be set later. However, catalogId, schemaName, and tableName are required and lack descriptions in the schema, and the description does not explain how to obtain or format these identifiers. It provides only the general 'table' framing, which is helpful but not sufficient to fully compensate for the missing schema 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 begins with a specific verb and resource: 'Create a cache for a table in the Peaka project.' It also explains the benefit of caching, which clarifies the tool's intended function. The mention that schedules can be changed later with peaka_update_cache helps distinguish creation from update, and the singular 'a table' implies the batch sibling is a different use case.

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

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

The description gives explicit workflow guidance: if projectId is unknown, call peaka_list_projects and ask the user, then remember the choice. It also notes that schedule expressions can be set later with peaka_update_cache, providing an alternative for post-creation changes. However, it does not specify when to use peaka_create_cache_batch instead, so it falls short of fully exhaustive usage 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?

The annotations only state readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context by revealing that the batch avoids partial-failure states where some caches are created and others aren't. This gives the agent a useful expectation about atomicity. It doesn't mention async behavior or return format, but that is not contradicted by 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, each earning its place: the batch purpose, the schedule expression semantics, and the projectId workflow. The main action is front-loaded and there is no filler or repetition of schema content.

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

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

The description covers the key selection criteria, schedule behavior, and projectId resolution, which is sufficient for correctly invoking a two-parameter batch creation tool. It could optionally mention checking cache status afterward, but that is not required for making the call correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving concrete schedule expression examples (PT6H, P1D, P7D, P30D) and explaining how to discover the projectId when it isn't already known. This operational guidance goes beyond the raw parameter definitions.

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

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

The description uses a specific verb and resource: 'Create caches for multiple tables in a single call.' It also differentiates itself from the sibling peaka_create_cache by explicitly mentioning the batch variant, so an agent can identify the tool's scope immediately.

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

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

It says explicitly to use this tool 'instead of repeated peaka_create_cache calls when caching many tables' and explains the benefit of avoiding partial failures. It also gives a concrete workflow for resolving an unknown projectId: call peaka_list_projects first and ask the user which project to use.

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 indicate this is a write operation (readOnlyHint false) and not destructive (destructiveHint false). The description adds useful context by disclosing the immediate outcome—creation of a saved query and return of its ID—and by noting the project selection prerequisite. It does not discuss permissions or duplicate-name behavior, but those are not critical gaps given the annotations.

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

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

The description is compact and front-loaded: purpose first, return value second, prerequisite workflow last. Every sentence carries useful information, and there is no filler or redundancy.

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

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

The description is adequate for this tool's complexity: five parameters are fully covered by the schema, and the description explains the return value and the project-selection workflow. Since there is no output schema, more detail about the full created query object's fields would be slightly helpful, but the key information an agent needs to call and use the tool is present.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds meaningful value beyond the schema by explaining how to obtain and remember projectId when unknown, and by clarifying that the returned ID is intended for peaka_execute_query. This is above the baseline for fully documented schemas.

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

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

The description names a specific verb ('Create'), a specific resource ('named, saved query'), and a specific location ('Peaka project's semantic layer'). It also states the return value (query object with ID), distinguishing this create operation from the many execute, get, update, and delete 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?

The description gives clear, actionable context: if the projectId is unknown, call peaka_list_projects first and ask the user which project to use, then remember it for later calls. It also notes the returned ID can be passed to peaka_execute_query, but it does not explicitly contrast this tool with alternative creation or retrieval approaches, so it falls short of a full when/when-not statement.

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

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

Annotations cover readOnlyHint = false and destructiveHint = false, so the tool's mutation profile is already known. The description adds value by disclosing the return value ('Returns the created catalog including its id') and explaining what a semantic catalog groups. No contradiction with annotations.

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

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

Four sentences, all purposeful: the core action is front-loaded, the concept is briefly defined, return behavior is stated, and practical projectId guidance is included. No redundant or filler content.

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

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

For a simple two-parameter creation tool with no output schema, the description is complete: it states the action, defines the domain concept, reports the return value, and handles the projectId discovery prerequisite. No critical information is missing.

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

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

Schema description coverage is 100%, with both name and projectId documented in the schema. The description itself does not add new parameter-level semantics 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 uses a specific verb and resource: 'Create a semantic catalog in the Peaka project' and explains what a semantic catalog is, distinguishing it from related tools like peaka_create_semantic_table and peaka_list_catalogs. It clearly defines the namespace concept and the artifact being produced.

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

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

The description gives explicit guidance on a key precondition: if the projectId is unknown, call peaka_list_projects first and ask the user which project to use, then remember the chosen projectId. It lacks an explicit 'don't use this if...' routing to alternatives like peaka_list_catalogs, but the context is clear enough for an agent to select the tool appropriately.

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 provide only coarse flags (readOnly=false, destructive=false), and the description adds a meaningful behavioral detail: the table is a queryable view over a saved query rather than a copied dataset. The instruction to remember the chosen projectId also flags conversation-state expectations. No contradiction with annotations was found.

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 about five sentences, with the core action and mechanism front-loaded before prerequisite tool guidance. Each sentence adds a distinct piece of information, and there is no filler.

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

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

For a 5-required-parameter creation tool, the description gives enough to select projects, get query/catalog IDs, and understand the resulting artifact. It does not mention return values, conflict behavior if tableName already exists, or verification steps, and there is no output schema to fill that gap, so it stops 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%, so the schema already documents every parameter's source. The main text mostly restates the provenance for queryId and catalogId and adds the conceptual 'queryable view' framing, but does not add new per-parameter constraints or formats. A baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Create a semantic table inside a semantic catalog') and clarifies the underlying mechanism ('backed by an existing saved query... queryable view'). This distinguishes it from sibling create tools like peaka_create_query and peaka_create_semantic_catalog.

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 names the exact predecessor calls needed to obtain queryId and catalogId ('Use peaka_create_query...') and instructs calling peaka_list_projects and asking the user when projectId is unknown. It does not explicitly list when-not-to-use cases or alternative table-level tools, but the workflow guidance is clear.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds useful behavioral nuance by stating the cache is removed entirely while the underlying table is unaffected. This clarifies the destructive scope beyond the bare annotation.

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

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

The description is compact and front-loaded: purpose first, then effects, then parameter sourcing, then prerequisite workflow. Every sentence contributes useful information and there is no filler.

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

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

For a two-required-parameter destructive action with no output schema, the description provides complete operational context: how to obtain cacheId, how to resolve projectId, what happens to the cache, and what is unaffected. An agent has everything needed to call it correctly.

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

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

The input schema covers both parameters at 100% with descriptions, so the baseline is already solid. The description goes further by explaining where cacheId comes from and prescribing the projectId discovery workflow, adding practical meaning beyond the schema fields.

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

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

The description starts with a clear verb-resource statement: 'Delete an existing cache in the Peaka project.' It also disambiguates scope by explicitly noting the underlying table is not affected, which separates this from other deletion tools like peaka_delete_query and peaka_delete_semantic_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?

The description clearly instructs the agent to use the cacheId returned from peaka_get_cache_statuses and provides a workflow for resolving an unknown projectId via peaka_list_projects. It does not explicitly compare against sibling delete tools, but the context is sufficient for deciding when to invoke this tool.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description merely restates the delete action without adding behavioral detail such as permanence, cascading effects, or confirmation requirements. It adds workflow information, but not meaningful behavioral context beyond what annotations provide.

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

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

Two compact sentences with no filler. The action is stated first, followed by the parameter acquisition workflow; every sentence performs a necessary function.

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

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

For a simple two-parameter destructive action with no output schema, the description covers both parameters and the prerequisite lookup calls. It could mention irreversibility or visible side effects, but the destructiveHint annotation already signals risk, and nothing critical to invoking the tool is missing.

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

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

Schema coverage is 100% and both parameters are documented, but the description adds valuable sourcing semantics: queryId is obtained from peaka_list_queries and projectId requires peaka_list_projects plus user confirmation. This goes beyond the bare schema descriptions.

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

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

States a specific verb ('Delete'), a specific resource ('saved query'), and the target system ('Peaka project'). This distinguishes it from sibling delete tools like peaka_delete_cache and peaka_delete_semantic_table by naming the exact resource type.

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

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

Gives explicit workflow guidance: obtain the queryId from peaka_list_queries, and if projectId is unknown, call peaka_list_projects and ask the user which project to use. It does not enumerate alternatives/exclusions, but the context is unambiguous and actionable.

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

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

Annotations already carry destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the crucial blast-radius disclosure — 'Removes the table mapping only; the saved query that backs it is not affected' — which is exactly the behavioral context an agent needs for a delete operation. It does not contradict the annotations.

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

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

Two tightly packed sentences with zero filler: the first front-loads the action and its scope boundary, the second delivers the prerequisite workflow. Every sentence earns its place and is immediately actionable.

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

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

For a 3-parameter delete with full schema coverage, annotations, and a stated blast radius, the description is nearly complete. The only meaningful gaps are the absence of return/confirmation behavior (no output schema exists) and no guidance on downstream effects for objects referencing the deleted table — minor omissions for a simply-scoped destructive tool.

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

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

Schema description coverage is 100%, with each parameter (projectId, catalogId, tableId) already documented in the schema, so the baseline is 3. The description adds a useful workflow note around projectId ('call peaka_list_projects first') but no additional format or syntax semantics 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: 'Delete a semantic table from a semantic catalog in the Peaka project.' The clarifying clause 'Removes the table mapping only; the saved query that backs it is not affected' precisely scopes the operation and differentiates it from siblings like peaka_delete_query and peaka_delete_cache without needing to open their 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?

The description gives an explicit, actionable workflow for the projectId prerequisite: 'call peaka_list_projects first and ask the user which project to use. Remember the chosen projectId for subsequent calls.' It also implies a when-not boundary ('the saved query that backs it is not affected'), signaling the agent should use a query-deletion tool for the backing query, though it never names an alternative sibling explicitly.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the description is not required to repeat safety. It adds a behavioral precondition—projectId must be known and user-confirmed—but does not describe response shape, latency, or failure modes. This is adequate but 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 sentences with no filler; the core action is front-loaded and the workflow guidance is actionable. Every sentence earns its place.

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

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

For a straightforward execution tool with two required string params, the description covers how to obtain both IDs and how to handle unknown projectId. It omits return-value expectations, but the absence of an output schema makes this a minor gap rather than a blocking issue.

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?

queryId has no schema description, and the description compensates by linking it to peaka_list_queries. projectId is covered by the schema and further reinforced by the list_projects workflow. Together, both parameters receive enough semantic grounding.

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 action—execute a saved query by ID in the Peaka project—and is distinguishable from sibling tools like peaka_execute_sql_query (ad-hoc SQL) and peaka_get_query (retrieval). The resource and mode of operation are clear.

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

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

Explicitly directs the agent to peaka_list_queries to obtain query IDs and to peaka_list_projects when projectId is unknown, including asking the user and remembering the choice. It does not contrast with execute_sql_query, but the given workflow is sufficient for correct invocation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds genuinely useful behavioral context beyond that: querying uncached tables yields limited results and can 'run forever,' which justifies the LIMIT instruction. This performance/limitation disclosure is valuable, though it does not mention response format, errors, or timeouts.

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 long but every section earns its place: the one-line purpose statement is front-loaded, and the numbered pre-flight checklist is scannable and actionable. The organization (purpose → prerequisites → fallbacks → projectId workflow) is logical and easy for an agent to follow.

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 only two required parameters, the dominant complexity is the cache-detection and project-selection workflow, which is covered exhaustively. The absence of any mention of result format is a minor gap for a SQL query tool, but nothing essential 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 coverage is 50%: projectId is documented in the schema, but the query parameter has no schema description. The description partially compensates by explaining how to obtain projectId (call peaka_list_projects, ask the user, remember it for later calls), but it adds nothing about the query parameter's format, dialect, or limitations — a real gap for the tool's primary input.

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 opening sentence states a specific verb ('Runs'), the resource ('the given sql query'), and the target ('Peaka'), which clearly conveys this executes raw SQL. It does not explicitly differentiate from the closely named sibling peaka_execute_query (which likely runs a saved query), so the distinction is left to inference rather than stated.

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 'BEFORE RUNNING THIS TOOL' section provides explicit sequential guidance: pull project metadata first, check isCached via peaka_list_tables, route to the create cache tool when tables are cacheable but uncached, and warn with LIMIT fallback if caching is rejected. It also names peaka_list_projects for projectId discovery, giving clear when-to-use context and named alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds what the response will contain (caching state, execution history, progress), but does not go further into behaviors like pagination, project-not-found behavior, or other edge cases. It does not contradict the annotations.

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

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

The description is compact: two sentences with a clear front-loaded purpose statement followed by concrete prerequisite instructions. There is no filler or redundant restatement of the schema.

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

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

For a single-parameter, read-only tool with no output schema, the description sufficiently covers what the tool does, what it returns, and the one prerequisite-sensitive situation. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

The schema already documents projectId at 100% coverage. The description adds practical usage meaning: if the agent does not know the projectId, it should call peaka_list_projects and ask the user, then remember the chosen projectId across the conversation. This aids correct invocation beyond the raw schema.

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

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

The description uses a specific verb and resource: 'Get all cache statuses for tables in the Peaka project.' It enumerates what is returned — 'current caching state, execution history, and progress' — making the tool's function immediately clear and distinguishable from sibling status tools such as get_materialized_query_statuses.

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 contextual guidance: if projectId is unknown, call peaka_list_projects first and ask the user, and remember the chosen projectId. This is helpful but does not explicitly contrast with alternative status tools or state when not to use this tool.

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

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

Annotations already declare read-only and non-destructive behavior. The description adds important context that the response shape varies by connection type and only `type` is guaranteed, which is especially useful since no output schema exists. It also mentions the projectId discovery workflow.

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 compact paragraphs with no filler. The purpose is front-loaded, followed by a response-variability caveat and then the prerequisite workflow. Every sentence adds useful information.

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

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

For a read-only lookup with two required parameters and no output schema, the description covers purpose, parameter provenance, the projectId workflow, and the variable response shape. It could enumerate possible connection types or common fields, but that is not necessary for correct invocation.

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

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

The schema descriptions already cover both parameters at 100% coverage. The description adds workflow guidance for discovering projectId and connectionId, but it does not add new type or format semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb and resource: 'Get connection-specific configuration detail for a data source connection.' It also distinguishes itself from peaka_list_connections by focusing on singular detail and explicitly pointing to list_connections for discovery.

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

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

Provides a clear workflow: use peaka_list_connections to discover the connectionId, call peaka_list_projects if the projectId is unknown, ask the user to choose, and remember the chosen projectId. It does not explicitly state when not to use this tool, but the context is sufficiently 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral detail beyond that: the tool returns schedule settings and both last and next execution times, and it can operate in a list-all or single-query mode depending on queryId presence. No contradiction with annotations exists.

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

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

The description is concise, front-loaded with the core purpose and return value, and uses a short second paragraph for the projectId workflow guidance. Every sentence earns its place without redundancy or filler.

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

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

For an inspection tool with no output schema, the description adequately summarizes the returned data (last refresh status, last/next scheduled times, interval/cron settings) and the two invocation modes. It also covers the prerequisite workflow for projectId. Minor details like pagination or status value formats are absent, but they are not essential 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?

Input schema coverage is 100% and both parameters already have meaningful descriptions, including the source of queryId from peaka_list_queries with queryType MATERIALIZED. The tool description reinforces the optional behavior of queryId but does not add much semantic information beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Inspect the auto-refresh state of materialized saved queries' in the Peaka project. It also enumerates the returned data (last refresh status, scheduled execution times, schedule settings), and the optional single-query vs. list-all behavior clearly separates it from sibling tools like refresh or cache status tools.

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

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

The description gives explicit operational guidance: it tells the agent to call peaka_list_projects first if projectId is unknown, ask the user which project to use, and remember that projectId for subsequent calls. It also explains when to pass queryId vs. omit it, but it does not explicitly contrast this tool with closely related alternatives such as peaka_get_cache_statuses or peaka_get_query.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by listing the exact possible statuses and clarifying this only checks status rather than triggering a refresh. No contradiction with annotations.

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

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

Compact and front-loaded: purpose and statuses come first, followed by a concise, actionable projectId instruction. Every sentence earns its place with no filler.

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

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

For a simple 2-parameter read-only status check, the description covers the action, resource, status vocabulary, and prerequisite workflow. A minor gap is the lack of explicit return-shape detail beyond the status enumeration, but this is not a severe omission.

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

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

Schema descriptions already fully document both parameters. The description adds meaningful workflow guidance for projectId—how to discover it, ask the user, and persist it—which goes beyond the schema. catalogId receives no additional semantic detail, but the schema suffices.

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 action (check status) on a specific resource (metadata refresh job for a catalog) and enumerates the possible statuses. This clearly distinguishes it from sibling refresh or query 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 prerequisite workflow: call peaka_list_projects first and ask the user which project to use if projectId is unknown, then remember it. It does not explicitly contrast this tool with sibling status/refresh tools, but the context is clear.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context that the call returns all metadata in one request and supports optional filters, but it does not disclose output shape, pagination, or whether metadata is cached/refreshed. With read-only annotations, a 3 is appropriate: it adds some value but not deep behavioral detail.

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 core purpose is front-loaded in the first sentence, and the following sentences provide prerequisite guidance without being excessively long. The instruction to remember the projectId is useful, though the separate workflow sentence could be tightened. Still, every sentence contributes meaning.

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

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

The tool is a read-only metadata discovery operation with 3 well-documented parameters and no output schema. The description states what it returns at a high level, how to call it, and how to obtain the required projectId. It lacks a specific output shape, but for a broad discovery tool that's acceptable; it is otherwise complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds only a minor clarification that catalogId and/or schemaName can be used as filters, but it does not introduce meaning beyond what the property descriptions already state. 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 starts with a specific verb+resource: "Get metadata for all catalogs, schemas, and tables in the Peaka project in a single call." This clearly separates it from the granular sibling tools like peaka_list_catalogs, peaka_list_schemas, and peaka_list_tables, since it emphasizes the single-call all-encompassing behavior.

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

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

The description explicitly says to use this tool to discover the data structure before writing queries, which is clear usage context. It also gives an alternative workflow for obtaining the required projectId by calling peaka_list_projects first. It does not explicitly name exclusion cases or contrast with the sibling list_* tools, but it gives enough context to select it appropriately.

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 readOnlyHint and destructiveHint annotations already signal a safe read operation, and the description adds useful behavioral detail by naming the exact returned object fields and the special auto-refresh schedule for materialized queries. It does not cover error or not-found behavior, but this is less critical for a read tool with strong annotation coverage.

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

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

The description is concise and front-loaded: the first sentence states the operation and return value, and the second gives a short, necessary workflow hint. Every sentence contributes useful information with no filler or repetition.

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

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

For a simple read-by-ID operation, the description fully covers what the tool returns, identifies both required parameters, and resolves the likely projectId prerequisite by directing the agent to peaka_list_projects. No crucial invocation information is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description adds workflow context around projectId but does not add much semantic meaning beyond the schema. A baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description uses a specific verb-resource pair ('Read a single saved query by its ID') and explicitly lists the returned fields, including SQL, query type, and refresh schedule. This clearly differentiates it from listing, executing, or status-oriented sibling tools.

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

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

The description gives concrete pre-usage guidance: call peaka_list_projects first if the projectId is unknown, ask the user which project to use, and retain that projectId for later calls. It does not explicitly mention when-not-to-use this tool versus alternatives, but the read-only purpose and schema-referenced peaka_list_queries provide clear context.

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

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

Annotations already mark this as read-only and non-destructive, so the description does not need to restate safety. It adds useful behavior beyond annotations by disclosing the response shape ('open-ended object map keyed by relation identifier') and the projectId discovery workflow, which helps the agent set expectations without contradicting the annotations.

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

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

The description is compact and front-loaded: it states the core action first, then the use case, then response shape, then the prerequisite workflow. Every sentence adds distinct value, with no filler or redundant restatement of the tool name.

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

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

Given the simple 2-parameter shape, read-only annotations, and no output schema, the description covers the essentials: what it returns, why it matters, and how to obtain a required parameter. The only minor gap is that the open-ended response object's key/value structure is not elaborated further, but the description explicitly flags it as open-ended.

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 catalogId and projectId are fully documented in the schema and the description does not need to repeat their definitions. The description does add contextual guidance around projectId (use list_projects if unknown), but this is procedural rather than parameter-level semantics, leaving the baseline at 3.

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 precise verb and resource ('Get table relationships (foreign keys) for a catalog'), immediately distinguishing this from sibling metadata tools like peaka_list_tables and peaka_list_columns. It also adds the JOIN-construction use case, which clarifies exactly what kind of information the tool provides.

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 frames when the tool is useful ('when constructing JOINs') and explicitly instructs the agent to call peaka_list_projects first if projectId is unknown, including asking the user for confirmation. It does not explicitly name alternatives to avoid, but the stated context is strong and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful behavior beyond that by disclosing that distinctFraction is an 'estimated fraction' and that the response includes table identifiers. No contradictions with annotations.

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

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

The description is two tight paragraphs with no filler. The first front-loads purpose and output semantics; the second provides a practical agent instruction about projectId discovery. Every sentence earns its place.

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

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

The description adequately covers return values and the projectId prerequisite, which is important given there is no output schema. However, with four required parameters and 25% schema coverage, the lack of input semantics for catalogId/schemaName/tableName leaves a meaningful gap, and error/edge-case behavior is unaddressed. It is workable but not fully complete.

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

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

Schema description coverage is only 25%, with only projectId documented in the schema. The description mentions catalog/schema/table identifiers in the output but gives no guidance on the meaning or format of catalogId, schemaName, or tableName as inputs. It only adds workflow context for projectId, so it fails to compensate for the low coverage.

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

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

The description uses a specific verb-resource pairing, 'Get column-level statistics for a table,' and spells out the exact return contents (catalog/schema/table identifiers and distinctFraction). This clearly separates it from sibling tools that list tables or columns, so an agent can distinguish it without opening the schema.

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

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

The description states that the tool is 'useful for cardinality estimation and query optimization,' providing explicit usage context. It also gives a concrete prerequisite workflow: if projectId is unknown, call peaka_list_projects and ask the user. It stops short of naming alternative tools or saying when not to use it, so it doesn't earn 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 is consistent. It adds useful behavioral context by stating the tool lists all available catalogs and returns names, types, and connection info, which is especially valuable since there is no output schema. It does not mention pagination, errors, or access requirements, but for a simple read-only list the key behavior is covered.

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

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

The description is two tight sentences: the first states the action and return contents, the second gives the operational prerequisite. There is no redundancy or filler, and the most important information is front-loaded.

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

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

For a low-complexity, read-only tool with one fully documented parameter, this description covers purpose, return summary, and projectId acquisition. The absence of an output schema leaves the exact response structure only summarized rather than fully specified, and potential pagination or limit behavior is not mentioned, but these are minor gaps for 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 description coverage is 100% for the single projectId parameter, so the schema already documents the parameter fully. The description only references projectId in the context of the prerequisite workflow and does not add format, constraints, or additional meaning beyond what the schema provides.

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

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

The description states a specific operation ('List all available catalogs') and identifies the returned data (catalog names, types, connection info), so the tool's purpose is clear. It does not explicitly differentiate itself from sibling discovery tools like peaka_list_schemas or peaka_list_tables, though 'catalogs' is a distinct resource.

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

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

The description gives explicit workflow guidance: if projectId is unknown, call peaka_list_projects first, ask the user, and retain the projectId for later calls. This clearly orients the agent on when a sibling tool is needed first, though it does not explicitly state when not to use this tool or compare it with other resource-listing tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about discovery prerequisites and return contents, but it does not address pagination, error cases, authentication, or rate limits. This is solid but not rich 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?

The main action is front-loaded, and the description stays compact with no filler. The first sentence gives purpose, the next gives return information, and the final paragraph gives necessary prerequisite and project-selection guidance. Every sentence earns its place.

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

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

There is no output schema, yet the description names the return contents and gives the required preceding discovery steps. It also handles the ambiguous projectId case explicitly. Combined with the readOnly/destructive annotations, an agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is only 25% (only projectId is documented), so the description carries most of the weight. It compensates by directing the agent to peaka_get_project_metadata for catalogId, schemaName, and tableName, and to peaka_list_projects for projectId, including asking the user and remembering the choice. It does not state exact identifier formats, but it gives usable meaning for all four required parameters.

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

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

The description states a specific verb and resource ('List all columns for a given table in the Peaka project') and specifies the output ('column names, data types, and constraints'). This clearly distinguishes the tool from sibling metadata-discovery tools like peaka_list_tables, peaka_list_catalogs, and peaka_list_schemas.

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

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

It gives explicit preparation guidance: call peaka_get_project_metadata first to discover catalogs, schemas, and tables, and if projectId is unknown, call peaka_list_projects and ask the user. It does not explicitly name alternate tools when this tool should not be used, so it lacks the when-not-to-use clarity needed for a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the non-mutating nature is covered. The description adds helpful return-value expectations (id, name, type, callback URL) and a user-confirmation workflow, but it does not disclose additional behavioral caveats such as pagination, permissions, or failure modes.

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

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

The description is succinct and front-loaded: purpose, return contract, sibling routing, and prerequisite workflow each earn their place. There is no filler or repetition that dilutes the guidance.

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

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

For a one-parameter read-only tool with no output schema, the description is complete: it explains what is returned, how to handle the required projectId, and where to go for more detail. An agent has enough context to call the tool correctly without needing additional structured fields.

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

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

The schema covers the single parameter 100% with a clear description, so the baseline is 3. The description adds practical meaning by explaining how to obtain an unknown projectId via peaka_list_projects and instructing the agent to remember it for subsequent calls, which goes beyond the bare schema definition.

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

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

The description uses a specific verb ('List') and clearly identifies the resource: 'all data source connections in the Peaka project.' It also distinguishes itself from the related sibling by explicitly mentioning peaka_get_connection_detail for connection-specific configuration, making the tool's scope immediately clear.

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

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

The description offers explicit usage guidance: it says to pair with peaka_get_connection_detail when configuration details are needed, and it directs the agent to call peaka_list_projects first if projectId is unknown. This is concrete, actionable routing that leaves little ambiguity.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description only needs to add context. It adds user-scoping ('accessible for the user') and implies the return contains projectIds, but does not address return shape, ordering, or pagination. This is consistent with the calibration example where scope plus annotations warranted a 3.

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

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

Two sentences, zero filler. The core function is front-loaded and the workflow guidance in the second sentence earns its place by explaining the tool's role in the broader API flow.

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 discovery tool with one optional, fully-documented parameter and read-only annotations, the description covers purpose, scope, and intended workflow. The only minor gap is the lack of return-shape detail given no output schema exists, but the explicit mention of discovering projectIds mitigates this.

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

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

Schema description coverage is 100% — the only parameter, 'search', is fully documented in the schema as a case-insensitive filter on project, workspace, or organization name. The description adds no parameter-level information, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('List all projects accessible for the user') plus the scope of the operation. It is clearly distinguished from siblings that target different resources (list_catalogs, list_schemas, list_tables), so an agent can select it correctly without inspecting schemas.

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

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

The second sentence gives explicit usage context: 'Use this tool to discover projectIds, then pass the chosen projectId to subsequent tool calls.' This tells the agent when in a workflow to invoke it, though it does not name alternatives or state explicit when-not-to-use conditions.

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 value beyond annotations by disclosing the return shape and the dependency behavior on peaka_list_projects. No contradiction with annotations exists.

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

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

Two compact sentences: the first front-loads the action and return values; the second delivers high-value workflow guidance about projectId resolution. Every sentence earns its place with zero filler.

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

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

With no output schema, the description properly compensates by stating what the tool returns (query names, SQL content, plain/materialized status). Combined with read-only annotations and the projectId workflow, nothing an agent needs to call this simple one-parameter tool correctly is missing.

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

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

Schema coverage is 100% for the single projectId parameter, setting a baseline of 3. The description elevates it by explaining how to obtain projectId (call peaka_list_projects, ask the user) and that it should be reused across subsequent calls — meaning beyond the schema's simple 'project ID to run against' definition.

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

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

The description names a specific verb and resource ('List all saved queries in the Peaka project') and states the return contents (query names, SQL content, plain/materialized flag). The 'all' scope distinguishes it clearly from the singular peaka_get_query sibling and the CRUD/execution siblings, so an agent can select it correctly 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?

The description gives explicit usage context and a concrete prerequisite workflow: if projectId is unknown, call peaka_list_projects first, ask the user which project to use, and remember it. This is clear, actionable guidance, though it stops short of naming alternatives/exclusions for when NOT to use this tool (e.g., for a single query's details).

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 useful context: the need to resolve projectId via peaka_list_projects and the 'all available' scoping. However, it does not disclose return format, pagination, or potential error behavior, which would be more informative for a simple listing 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?

Two sentences with no redundancy. The first sentence front-loads the core purpose, and the second earns its place by providing a concrete workflow instruction. The description is appropriately sized for the tool's simplicity.

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

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

The tool is low complexity and annotations cover safety, but the description is incomplete in one key respect: it explains how to resolve projectId but not catalogId. An agent that does not already have catalogId has no guidance to call peaka_list_catalogs. With no output schema, a mention of the return shape would also help, though the name makes it obvious.

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 50%: projectId has a description, but catalogId has none. The description adds meaning for projectId by instructing the agent to obtain it via peaka_list_projects and user confirmation, and implies catalogId is the identifier of the 'given catalog'. Yet it does not explain how to discover catalogId (e.g., via peaka_list_catalogs) or its expected format, leaving a 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?

The description states a specific action ('List'), a clear resource ('all available schemas'), and the scope ('for a given catalog in the Peaka project'). This clearly differentiates it from sibling tools like peaka_list_catalogs, peaka_list_tables, and peaka_list_columns, which operate at different levels of the metadata hierarchy.

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

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

Provides clear context for when to use the tool: when you need schemas for a catalog. It also includes an explicit prerequisite workflow—if projectId is unknown, call peaka_list_projects first and confirm the project with the user. However, it does not explicitly compare against alternatives like peaka_list_tables or peaka_list_catalogs, nor does it state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond annotations: it requires a known projectId, instructs the agent to call peaka_list_projects if missing, and tells the agent to persist the chosen projectId across the conversation. This is meaningful operational guidance.

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: a one-sentence purpose statement followed by two concise, high-value instructions about projectId handling. Every sentence earns its place, and the core purpose is front-loaded before the workflow note.

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

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

The description covers the purpose and the projectId prerequisite workflow, which are important. However, since there is no output schema, it does not state what the returned table list looks like or whether it includes metadata. It also does not mention that catalogId and schemaName can be discovered via sibling tools like peaka_list_catalogs and peaka_list_schemas. The description is adequate but has clear informational gaps.

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

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

Schema description coverage is only 33%, and only projectId has a description. The description partially compensates by saying 'for a given catalog and schema', mapping to catalogId and schemaName, but it does not explain what these values are, how to obtain them, or what formats are expected. The parameter names are fairly self-explanatory, but the description adds limited semantic value beyond them.

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

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

The description clearly states a specific verb and resource: 'List all available tables for a given catalog and schema in the Peaka project.' This distinguishes it from sibling tools like peaka_list_catalogs, peaka_list_schemas, and peaka_list_columns by naming the exact object being listed (tables) and its scoping context.

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

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

The description gives clear context for when to use the tool: to get all tables within a specific catalog and schema. It also provides a concrete conditional workflow: if the projectId is unknown, call peaka_list_projects first and confirm with the user. However, it does not explicitly mention when not to use it or compare it with alternatives like peaka_list_columns.

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 is consistent with this. It adds meaningful behavioral context beyond annotations: the golden SQL store is semantic/vector-based retrieval, the found query should be reused verbatim, and projectId is expected to persist across the conversation once chosen. This goes beyond basic safety 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?

Three sentences with no redundancy. The core purpose is front-loaded, and each subsequent sentence earns its place by providing workflow guidance and a prerequisite. Nothing could be cut without losing value.

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

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

The tool is low-complexity (2 simple params, no output schema, no nested objects), and the description covers purpose, usage flow, and projectId resolution. The only omission is what happens when no matching query is found — whether the tool returns empty results or an error — which matters for agent decision-making since there is no output schema to clarify this.

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 50% (projectId has a schema description, query does not), so the description carries real weight here. It meaningfully enriches projectId by explaining how to obtain it (via peaka_list_projects) and that the user must confirm the choice. The query parameter's meaning is only implied by the first sentence rather than stated, which is a minor 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?

The first sentence states a specific verb and resource: 'Query question/sql pairs from Peaka's golden sql vector store.' This clearly differentiates the tool from siblings like peaka_execute_query (execution) and peaka_list_queries (listing) — this one retrieves reusable question/SQL pairs for lookup purposes.

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

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

The description provides an explicit decision procedure: use this tool to look for an existing matching query and reuse it if found; otherwise fall back to 'other tools' to derive tables and write a new query. It also specifies the prerequisite of calling peaka_list_projects when projectId is unknown. The only gap is that the alternatives are referred to generically as 'the other tools' rather than named explicitly.

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 indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to re-state mutation safety. It adds the source of the cacheId and the projectId workflow, but it doesn't disclose potential side effects, async behavior, or what triggering a refresh entails beyond the action itself.

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

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

The description is compact, front-loads the main action, and uses the second sentence for essential dependency guidance. No unnecessary filler or repetition of schema information.

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

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

For a simple two-parameter trigger tool, the description provides the necessary input-sourcing workflow and action clarity. It doesn't describe what the refresh returns or when a full refresh should be chosen over incremental, but it is still adequate for invoking the tool correctly.

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

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

Schema coverage is 100%, so both parameters are documented. The description adds valuable provenance guidance: cacheId comes from peaka_get_cache_statuses and projectId may need to be discovered via peaka_list_projects, which helps the agent supply correct values.

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

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

The description uses a specific verb ('Trigger') and resource ('full refresh on an existing cache'), which clearly states the action and object. The phrase 'full refresh' distinguishes it from the incremental refresh sibling without needing to open the schema.

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

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

The description gives explicit workflow guidance: use the cacheId returned from peaka_get_cache_statuses, and if projectId is unknown, call peaka_list_projects and ask the user. It does not explicitly contrast with peaka_refresh_cache_incremental, but the 'full refresh' wording implies the distinction.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description need not restate safety. It adds useful behavioral context: the operation is incremental, fetches only new/changed rows, and requires an existing cache. However, it does not mention whether the refresh is asynchronous, what the response is, or how to monitor completion, leaving some behavioral ambiguity.

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

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

The description is three sentences with no filler. The first sentence states purpose, the second explains the benefit and parameter source, and the third gives a practical projectId workflow. Every sentence earns its place.

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

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

The description covers the key prerequisites: an existing cache, the cacheId source, the projectId discovery workflow, and the incremental-versus-full distinction. Since there is no output schema, it could be slightly more explicit about return values or asynchronous behavior, but for a simple trigger tool the guidance is largely 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 100%, so the schema already explains both parameters. The description adds value beyond the schema by specifying that cacheId comes from peaka_get_cache_statuses and by explaining how to obtain and remember projectId for subsequent calls. This is meaningful operational guidance that the schema alone does not provide.

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

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

The description opens with a specific verb and resource: 'Trigger an incremental update on an existing cache in the Peaka project.' It also clearly contrasts with a full refresh by stating it 'fetches only new/changed rows,' making the purpose unmistakable and distinguishing it from peaka_refresh_cache_full.

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

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

The description gives clear context: use this for incremental updates that only fetch new/changed rows and are faster than a full refresh. It also provides a workflow for resolving projectId via peaka_list_projects when unknown. It does not explicitly name the sibling peaka_refresh_cache_full, but 'full refresh' clearly alludes to the alternative.

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

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

Annotations already mark the operation as not read-only and not destructive. The description adds that the operation is a refresh on a saved materialized query but does not disclose whether it is asynchronous, how completion is observed, or what it returns, leaving a gap 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?

Four short sentences, with the core purpose first and no filler. Each sentence carries operational value; the workflow for projectId is the only slight extension but is justified.

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

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

For a two-parameter mutation tool, the description covers purpose, parameter provenance, and a project-selection workflow. However, with no output schema, it never states the return value or whether refresh is asynchronous and should be followed with peaka_get_materialized_query_statuses, leaving a real gap for an agent to know the expected response and follow-up.

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 input schema already fully documents both required parameters, so the baseline is 3. The description adds actionable parameter context beyond the schema: the queryId must come from peaka_list_queries with queryType 'MATERIALIZED', and projectId should be resolved via peaka_list_projects and then remembered for the session.

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 pair ('Trigger a refresh on a materialized saved query'), and further disambiguates by requiring queryType 'MATERIALIZED' from peaka_list_queries, distinguishing it from execute/status/cache 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?

It explicitly directs the agent to obtain queryId from peaka_list_queries filtered to MATERIALIZED queries, and instructs to call peaka_list_projects first if projectId is unknown and to remember the chosen projectId. This gives clear when-to-use and precondition 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 only minimal annotations, the description carries the behavioral burden and does so well: it reveals the operation is long-running, asynchronous, returns immediately, and does not wait for completion. It does not describe possible side effects or failure behavior in detail, but the status-polling instruction mitigates that 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?

The description is compact and every sentence earns its place: purpose, trigger condition, async behavior, polling path, and projectId resolution. Important constraints are front-loaded before secondary guidance.

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

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

The description is nearly complete: it covers when to use, async behavior, how to track progress, and how to discover the projectId. The main omission is that if catalogId is unknown, it does not tell the agent to use a sibling like peaka_list_catalogs to find it.

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

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

The input schema already describes both parameters at 100% coverage, so the baseline is 3. The description adds useful extra meaning for projectId by telling the agent to call peaka_list_projects and ask the user if it is unknown, but it does not similarly enrich catalogId.

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

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

The description uses a specific verb, 'Refresh', and names the resource, 'project metadata', while also scoping the operation to a specific catalog. This clearly differentiates it from peaka_get_project_metadata and other query/materialized-query 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?

The description explicitly states when this tool should be used — only when a data source has structurally changed — and instructs the agent to poll peaka_get_metadata_refresh_status afterward. It also gives concrete guidance for resolving projectId via peaka_list_projects, but it does not explicitly point to an alternative for simply reading current metadata.

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 description discloses two non-obvious behaviors beyond what annotations convey: the endpoint 'replaces — not merges — the schedules, so both incrementalSchedule and fullRefreshSchedule must be supplied with the full intended state every call,' and the warning that 'the backend may clamp to its allowed range — check it.' These are exactly the behavioral traits an agent needs to avoid sending partial updates or assuming the response equals the request. The annotations (idempotentHint=true, destructiveHint=false, readOnlyHint=false) are fully consistent, so there is no contradiction.

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

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

The purpose is front-loaded in the first sentence, followed by the critical replace semantics, schedule format, clamping warning, and projectId workflow — each sentence earns its place. It is not a 5 because the ISO-8601 examples (PT6H, P1D, P7D, P30D) duplicate what the schema already provides, and the two projectId sentences could be merged without losing information.

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

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

With no output schema present, the description compensates by telling the agent that 'the response reflects the schedule actually applied' and to check it due to clamping — the most important return-value behavior. Combined with the schema covering cacheId sourcing ('Available from peaka_get_cache_statuses') and the description covering prerequisites, replace semantics, and schedule formats, the essential calling information is present. It stops short of 5 because the response shape is only sketched and failure-mode behavior is not addressed.

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 each parameter's meaning, format (BASIC with ISO-8601 pattern, or NONE), and replace behavior, so the baseline is 3. The description adds value by emphasizing that both schedules must carry the full intended state on every call (clarifying their interaction) and by noting the applied value may be clamped, which affects how the agent should interpret the parameters it sent. This modest but real increment justifies a 4.

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

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

The description opens with a specific verb and resource: 'Update cache settings on an existing cache in the Peaka project.' This is clearly distinct from sibling tools like peaka_create_cache, peaka_delete_cache, and peaka_refresh_cache_full/incremental, which operate on cache lifecycle and data refresh rather than schedule settings. The 'replaces — not merges — the schedules' detail further sharpens the scope beyond a generic update.

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

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

The description gives explicit workflow guidance: 'If you do not already know the projectId for the current task, call peaka_list_projects first and ask the user which project to use,' plus a session-memory instruction to remember the chosen projectId. However, it does not explicitly draw when-not-to-use boundaries against the sibling refresh tools (e.g., when the intent is to trigger a refresh rather than change schedule settings), so the contrast with alternatives is implied rather than stated.

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

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

Annotations already provide idempotentHint and destructiveHint, so the bar is lower. The description adds useful behavior beyond annotations: the schedule parameter is only relevant for materialized queries and is ignored for plain queries, and at least one of displayName, inputQuery, or schedule must be supplied. No contradiction with annotations.

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

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

The description is compact and front-loaded. The core purpose appears in the first sentence, followed by a terse constraint and then a practical projectId workflow. Every sentence contributes useful 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?

Given five parameters, no output schema, and an update operation, the description covers the essential context: prerequisite lookup, required fields, and schedule limitations. It does not describe the return value, but the tool's purpose and invocation requirements are otherwise complete enough for an agent to use it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful value by stating the at-least-one-of-three constraint, which is not captured in the schema's required list, and by reinforcing the materialized-only schedule 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?

The description states a specific verb and resource: "Update an existing saved query in the Peaka project." It further clarifies what can be changed (display name, SQL body, schedule), clearly distinguishing this from sibling tools like peaka_create_query, peaka_get_query, or peaka_delete_query.

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

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

It gives clear context that this is for an existing saved query and requires at least one updatable field. It also provides a concrete workflow: call peaka_list_projects first if projectId is unknown and remember the chosen projectId. It does not explicitly say 'use peaka_create_query for new queries,' but the existing-vs-new distinction is clear enough.

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