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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds valuable behavioral context: it rotates the current session's credential, requires admin writes, and notes that passwords are never logged or echoed. This goes well beyond the structured annotations and warns the agent about irreversible side effects.

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

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

The description is two sentences with no filler. The core action and prerequisites are front-loaded, and the security note about logging is a meaningful addition that 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?

Given the full parameter schema, destructive/read-only annotations, and the description's coverage of prerequisites, side effects, and security behavior, an agent has everything needed to invoke this tool correctly. No output schema exists, but the description does not need to explain return values for this mutation.

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 old_password, new_password, and confirm. The description reiterates that confirm=true is required and explains the credential rotation, but it does not add new parameter-level details beyond what the schema's confirm description already states.

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

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

The description states a specific verb and resource: 'Change the authenticated user's password.' This clearly distinguishes it from sibling tools like update_config or set_user_access, which operate on different resources. The title reinforces the same precise scope.

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

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

The description gives explicit prerequisites: admin writes must be enabled (PORTAL_ALLOW_ADMIN_WRITES=1) and confirm must be true. It does not name alternatives, but no sibling tool appears to be a password-change alternative, so the context is sufficient for an agent to know when to invoke it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate that this can delete. However, it adds valuable context beyond annotations: the dry-run default, the distinction between VC-recorded (restorable) content deletes and non-restorable db_modification deletes, and the safety criteria (unreferenced, not recently touched). This is rich behavioral disclosure that goes beyond what annotations provide. The only minor gap is not explicitly stating that the tool is idempotent (though annotations declare idempotentHint=true), but the description's detail on safety and restorability is strong.

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

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

The description is dense but well-structured. It front-loads the matching criteria and the dry-run default, then explains the deletion behavior and restorability. Every sentence adds meaningful information — no filler. The use of em-dashes and parentheticals packs a lot of detail without becoming unwieldy. It's appropriately sized for a tool with 6 parameters and complex safety semantics.

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

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

For a tool with 6 parameters, no output schema, and destructive potential, the description is remarkably complete. It covers what matches, what gets deleted, safety criteria, restorability, and defaults. The only thing an agent might want is an example output format for the dry-run report, but the description already explains what the report contains (every match, why it matched, what references it). Given the complexity and the annotations covering safety, this is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds value by explaining the default behavior (kinds default to query/block/db_modification, max_delete default 50, older_than_minutes default 60) and the safety semantics (older_than_minutes protects running loops, include_unnamed never applies to db_modifications). This goes beyond the schema's basic descriptions, providing operational context that helps an agent choose correct parameter 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 clearly states the tool's purpose: finding and optionally deleting records that scratch conventions mark as disposable. It specifies the matching criteria (name starting 'TMP ·', 'scratch'/'tmp' tag, '(delete me)' in name) and distinguishes it from the general delete_resource sibling by emphasizing the dry-run default and the gated delete path. This is a specific verb+resource with clear scope.

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

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

The description explicitly explains when to use this tool (for cleaning up scratch leftovers) and contrasts it with delete_resource, noting that deletions go through the same gated path. It also explains the dry-run default and the confirm=true flag for actual deletion, giving clear guidance on when to use the tool versus alternatives. The mention of 'loop hygiene' in the title further clarifies the intended use case.

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

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

With readOnlyHint=true already provided, the description adds context about optional parameter behavior (omitting resource lists all resources) and the nature of the returned data (schema fields, verbs, risk domain). While it doesn't detail error handling, it enriches the behavioral understanding beyond the 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 concise, consisting of two sentences. The first sentence states the primary function, and the second provides an alternative usage and a recommendation. It is well-structured, front-loaded, and contains no fluff.

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 simplicity of the tool and the absence of an output schema, the description is complete. It covers the main purpose, the optional parameter behavior, and provides a clear usage context. It does not leave significant gaps for an agent to infer.

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

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

The tool description adds crucial meaning to the 'resource' parameter by explaining that omitting it lists all resources, which is not mentioned in the schema description. This clarifies the optionality and the effect of not providing the parameter, making the tool's behavior fully understandable.

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 tool's function with a specific verb ('Show') and enumerates the information it provides (path, write fields, required-to-create fields, supported verbs, risk domain). It also distinguishes itself by naming a secondary mode (listing all resources) and explicitly positioning it as a precursor to create/update operations, setting it apart from sibling tools like get_resource or create_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 usage guidance: 'Call this before create_resource/update_resource' and notes the behavior when omitting the resource parameter. This clearly tells the agent when to use this tool versus alternatives, providing both a typical workflow and an alternative use case.

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 include readOnlyHint=true, and the description reinforces it. It adds genuinely useful behavioral context about a default 1,000-row cap, truncation notification, and the risk of unlimited queries. This goes beyond generic read-only labeling and explains important edge behavior.

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

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

The description is efficient and well-structured: first the core action, then query parameters, then the critical row-limit behavior and caveat. Every sentence adds operational knowledge and the read-only note is prudently repeated despite the annotation.

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 read-only query executor with no output schema, the description covers what an agent needs to invoke it correctly: the identifier, parameters, limit behavior, truncation behavior, and safety profile. It does not describe the exact response structure, but that is minimized by the absence of an output schema and the simplicity of the resource.

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 documents all 3 parameters with rich descriptions, so the baseline is 3. The description adds meaningful usage details above the schema: the default limit of 1,000, the effect of limit=0, and the shape of params as a name/value map. This 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?

States the exact action ('Run a saved query by id'), the resource type (saved query), and the outcome (return its results). Distinguished from sibling tools like run_db_modification and get_resource by emphasizing saved, read-only query execution.

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 practical usage guidance: how to pass query parameters, the default row cap, why it exists, how to override it, and the warning about limit:0. It does not explicitly name alternatives or state when not to use this tool, but the context suggests this is the canonical read query executor.

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, so the description correctly implies no side effects. It adds behavioral details beyond the annotation: case-insensitive substring matching, exact-id support, default non-admin kinds, and the effect of `kinds` to include admin kinds. These are useful runtime behaviors not captured by structured metadata.

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 with the core purpose, then packs matching behavior, defaults, and filtering into a logically structured sentence. It avoids redundancy with schema descriptions and uses compact phrasing. Slightly dense but not verbose; 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?

Given the tool's complexity (multiple kinds, filters, pagination via offset/limit), the description covers key usage aspects: matching semantics, defaults, and filtering. The output schema exists, so return values don't need explanation. It lacks explicit mention of pagination behavior, but that is documented in the schema (offset/limit parameters). Satisfactory for a search 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 has 100% description coverage, so the baseline is 3. The description adds value by explaining the default behavior of `kinds` (all non-admin kinds) and how to include admin kinds, which is not explicit in the schema. It also clarifies that `query` can be a substring or exact id. This enriches parameter meaning beyond the raw schema 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 clearly states the tool searches records across resource kinds by name/title, with a specific verb ('Search records') and resource scope ('across resource kinds'). It distinguishes from siblings like get_resource (which fetches a specific resource) and list_resource (which lists whole collections) by explicitly mentioning the search capability and avoiding full client-side listing.

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 context on when to use it: for finding records by name without listing whole collections, which implies it's preferred over list_resource for name lookups. It also explains defaults and how to narrow with `kinds` and `tag`, but does not explicitly state when *not* to use it (e.g., when you need exact resource retrieval via get_resource). The guidance is implicit rather than explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile and external variability. The description adds no additional behavioral context beyond restating the fetch operation, but it does not contradict the annotations and the annotations carry the burden well.

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

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

A single, front-loaded sentence with no filler. It states the action and the target resource economically, which is ideal for such a simple tool.

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

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

For a parameterless read-only tool, the description is largely sufficient. With no output schema, it could briefly mention the return format or that it returns the full configuration document, but the phrase 'configuration document' already implies the core outcome.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter behavior because there are none to document.

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 ('Fetch') and a precise resource ('the portal's configuration document'), clearly distinguishing it from siblings like update_config and reload_config. Even without reading the schema, an agent knows exactly what this tool retrieves.

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 implies the tool is for retrieving configuration, which is clear context. However, it does not explicitly mention that users should prefer this over get_capabilities or describe when not to use it. For a simple getter this is acceptable but not explicit.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds value by specifying the exact content (severities and conventions text) and relates it to the enforcement behavior of mutation siblings, beyond what annotations convey.

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

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

Two sentences with zero redundancy. The first sentence states what is returned; the second directly tells the agent when to use it. All information is front-loaded and purposeful.

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, parameterless read tool with readOnlyHint=true, the description fully covers what an agent needs to know: the tool returns the active rules and their enforcement context. No output schema exists, but the description outlines the return contents adequately.

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

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

The tool has zero parameters, and the schema coverage is trivially 100% with no properties. Per the rubric, a score of 4 is the baseline for no-parameter tools; the description cannot add parameter meaning since none exist, but it does clarify the output content instead.

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 ('Return'), a clear resource ('active block-authoring rules'), and enumerates the content ('per-rule enforcement severities and the conventions text'). It further ties the tool to create_block/update_block enforcement, differentiating it from sibling config and access 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?

Explicitly instructs to read this tool to understand what create_block/update_block will enforce, giving a concrete call-to-action. It does not mention when to avoid this tool or use alternatives, but the provided usage context is clear and sufficient.

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 openWorldHint=true, so the description is not expected to repeat safety information. The description adds that this is a combined lookup, but does not disclose error behavior, whether permissions are direct or effective, or any special values the tool accepts. This is acceptable but not particularly 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?

The description is short and front-loaded with the main purpose. The second sentence provides useful routing context but is slightly ambiguous because the parenthetical about 'me' could be read as applying to get_user_access when it likely applies to get_resource. Overall it is efficient with minimal waste.

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 one-parameter read tool, the description gives a reasonable high-level summary of the return content (groups and permissions) and points to the correct sibling for raw user records. However, with no output schema, it does not specify the shape, whether permissions are resolved/inherited, or behavior for invalid user IDs, leaving some gaps for an agent.

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 fully describes user_id as 'User UUID' with 100% coverage, so the baseline is 3. The description does not add significant parameter-level detail; the mention of 'me' as the authenticated user appears to refer to get_resource, not necessarily to this tool's user_id parameter. Thus the description adds no meaningful semantic value beyond the schema.

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

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

The description clearly states the tool returns a user's groups and permissions in one call, with a specific verb ('Return') and resource ('a user's access'). It distinguishes itself from simple user-record retrieval by mentioning get_resource for the user record itself, making the tool's specific purpose unambiguous.

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

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

The description implies when to use this tool: when you need both groups and permissions together. It also points to get_resource for the raw user record, which is a helpful alternative. However, it does not explicitly state exclusions or when not to use this tool, leaving some inference required.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description only needs to add behavioral context. It does so by noting the tool returns version and about info and is meant for gating. It doesn't contradict annotations and provides useful purpose beyond what annotations state.

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 short sentences, front-loaded with the primary purpose. The second sentence adds necessary usage guidance. No redundancy or fluff.

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 sufficient for a zero-parameter, read-only info tool. It explains the use case (gating) and distinguishes from check_connection. It could mention what 'about info' contains, but that's minor. Overall, it's complete enough.

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

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

There are no parameters, so the schema is trivially 100% covered. The description adds no param semantics but none are needed. Baseline for zero-parameter tools is 4; it doesn't lose points.

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 ('Fetch the portal version and about info') and clearly distinguishes it from check_connection by noting it gates version-specific endpoints. The resource is unambiguous and the tool's role is clear.

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

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

It explicitly states when to use (gate version-specific endpoints) and when not to (to confirm connection, call check_connection instead). This gives the agent clear decision criteria and an alternative tool name.

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

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

Annotations carry only readOnlyHint and openWorldHint; the description carries the real burden and nails it, disclosing non-obvious runtime behavior the annotations can't: nullable `total` when first pages fetch server-side, the walk-until-truncated=false protocol, byte-capping at PORTAL_LIST_BYTE_CAP with silent auto-projection to { id, name } plus a `note` field. These are exactly the pagination and envelope edge cases that would cause silent agent bugs, and they go well beyond what readOnlyHint/openWorldHint convey.

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

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

Dense but purpose-built: a single paragraph that moves logically from what → when → return contract → edge cases → routing, with the most important fact (purpose + example) front-loaded. The one blemish is that the sentence 'Optional `query` adds URL query params' largely restates the schema, and the wall of nested parentheses is heavy on the eyes. For a tool this complex (6 params, byte caps, portal variability), the density is earned.

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 tool's complexity — open-world portals, client- vs server-side pagination, byte caps, an 18-value enum, and a self-described output envelope — the description covers every call-relevant dimension: the exact envelope { total, offset, limit, returned, truncated, records }, how to iterate, what total:null means, how to detect truncation, and when to route elsewhere. No return-format gap exists because the description dually serves as de facto output documentation (the envelope is described inline even though an output schema is flagged). An agent could implement correct pagination and projection entirely from this text.

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

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

Schema coverage is 100%, so the baseline is 3. The description clears that bar by adding behavioral consequences tied to parameters that the schema doesn't state: when to prefer only_names/fields for discovery, the interplay between byte caps and field projection, and the fact that `query` lets the portal (not just the client) do the work. It stops short of adding a 5 because the schema already carries its weight with examples like { only_names: true } and ['name','updated_at']; the description refines rather than rescues the parameter docs.

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

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

Specific transitive verb plus explicit resource scope ('List records of a resource (block, datasource, layout, ...)') with the 18-value enum in the schema to back it up. It differentiates from siblings by naming its role — 'Use this for discovery — e.g. find a datasource UUID before authoring a block' — and explicitly distinguishes itself from get_resource ('...for detail') and describe_resource ('Call describe_resource for fields and supported verbs'). An agent can select this tool for listing/discovery and route detail work elsewhere.

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

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

Gives explicit when-to-use ('Use this for discovery') with a concrete workflow example, and names the alternative with the condition that selects it: 'prefer only_names/fields for discovery and get_resource (summary/fields) for detail.' It also documents how to fully consume the result set ('walk offset for the rest'), so the agent knows the shape of the interaction, not just when to fire it. This is explicit routing guidance, not implicit inference.

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

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

The description calls the tool a pure function, which adds determinism/no-side-effect context beyond the readOnlyHint annotation. It also discloses useful behaviors: stable slugs, facet-tag generation, resource kinds omitting the kind word, source markers with a 'live' default, and conformance grading. No contradiction with 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 dense but front-loaded with the core convention and both actions. Every sentence earns its place, and the long enumerations are necessary because the schema does not provide them.

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-mode tool with seven parameters and no output schema, the description provides enough to call it correctly: required fields per action, all allowed vocabularies, source default behavior, and what each mode returns at a conceptual level. The exact parse grading rubric is not needed for selection or 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 covers parameter names, but the description supplies the full controlled vocabularies it omits: scope code mappings, the complete kind list, source facets, and the conditional omission rule for resource kinds. It also clarifies requiredness per action, which goes meaningfully beyond the input schema.

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

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

The description states the exact function: the `SCOPE · Kind Subject` naming convention as a pure function, with suggest generating a display name, slug, and tags, and parse decomposing and grading a name. It clearly distinguishes the two modes and is unlike any of the resource/config 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?

It explicitly says to prefer suggest over hand-naming and explains why: consistency of derived slugs and tags. It also makes the parse mode's purpose obvious for existing display names, so an agent can select the right action without guessing.

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 openWorldHint: true, so the description does not need to reiterate side effects. The description itself is transparent about the operation: it samples and returns statistics and rows, implying no modifications. There is no contradiction between the description and annotations, and the description adds detail about the read-only nature by using the verb 'sample'.

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 verbose and contains redundant phrasing. For example, it repeats 'so you see real column names and literal values in the same call' and then again 'match a block's column constants to reality.' The em-dash style and the extra explanatory sentence ('Exactly what you need...') could be condensed. While not overly long, it lacks conciseness and could be streamlined without losing 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 description thoroughly explains what the tool returns (per-column stats and sample rows) and its purpose. However, it does not mention error scenarios, limits beyond parameter defaults, or how the results are formatted. Since there is no output schema, the description partially compensates by describing the output structure, but it could be more comprehensive regarding edge cases (e.g., empty datasource, large datasets). Overall, it is sufficient for a typical agent interaction.

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

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

All four parameters are fully described in the schema with clear meanings: datasource_id, sample_size, sample_rows, and distinct_cap each have detailed descriptions. The schema coverage is 100%, and the descriptions provide sufficient context (e.g., 'Stop counting distinct values past this many per column'). No additional clarification is needed in the tool description beyond what is already provided.

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 tool's purpose: sampling a datasource and returning per-column statistics plus raw sample rows. It explicitly lists what is returned (inferred type, non-null/empty counts, distinct value count, sample values, min/max) and explains the benefit ('so you see real column names and literal values'). This is specific and unambiguous, distinguishing it from generic resource inspection 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 includes a clear use case: 'Exactly what you need to design filters, choose chart dimensions, pick aggregations, and match a block's column constants to reality.' This indicates when to use the tool, though it does not explicitly contrast with sibling tools like describe_resource or list_resource. It implies a data profiling context, which is sufficient guidance for an agent 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 description extensively discloses behavioral traits beyond annotations: no snapshot/rollback for database writes, the need for confirm, the guard against unscoped writes, and the best-effort classifier that fails closed. This aligns with annotations (destructiveHint=true, readOnlyHint=false) and adds crucial risk context an agent needs.

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

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

The description is compact but dense, with the primary action stated first, followed by critical constraints and parameter usage. Every sentence contributes meaningful information (prerequisites, safety checks, parameter formats). It's not bloated, but slightly longer than necessary; still excellent.

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 tool's complexity (7 params, safety guards, no output schema), the description covers all essential aspects: the operation, prerequisites, guard behavior, parameter passing, and failure modes. An agent has enough information to invoke it correctly and understand risks without further reference.

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

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

Schema coverage is 100% with descriptions for all params. The description adds value by explaining the semantics: params is a { name: value } map, params_list is for bulk rows, confirm guards against accidental writes, and allow_unfiltered is required for mass writes. This enriches the structured schema details.

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 (execute) and resource (saved db_modification), and clarifies it's for INSERT/UPDATE/DELETE operations. It clearly distinguishes from siblings like execute_query (which likely reads) by emphasizing it writes to a database, and the 'by name' scoping differentiates from other modification 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?

Explicit usage conditions are given: requires data writes enabled (PORTAL_ALLOW_DATA_WRITES=1), confirm=true, and describes when it refuses to run (unscoped mass writes without allow_unfiltered=true). While it doesn't name alternative tools, it provides clear prerequisites and boundary conditions, making it good but not perfect.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description reveals that scratch-marked records are excluded, that it compares against a baseline when version control is on, and that 100 has a specific meaning. These are meaningful behavioral traits not covered by annotations. It does not mention potential side effects beyond baseline updates, but the annotations reduce the burden.

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 a single dense paragraph that packs essential information without fluff. Every sentence contributes: scope, exclusions, baseline behavior, and the meaning of 100. It is slightly long but well-organized, with the core purpose front-loaded. The structure is functional, though it could be broken into list form for easier scanning.

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 there is no output schema, the description implicitly states what the tool returns (scores and baseline deltas). It covers key prerequisites like version control on for baseline, and mentions the detail_below behavior. It doesn't explicitly state the output format or error handling, but for a scoring tool with simple boolean and integer parameters, the information is largely sufficient to invoke it correctly.

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

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

The schema already documents both parameters fully (coverage 100%), so the baseline is 3. The description adds extra meaning for update_baseline by explaining the loop discipline and when to set it to true, which goes beyond the schema's simple 'save as baseline' note. However, it duplicates the detail_below description from the schema, so the net addition is moderate.

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 tool's function: 'Score every block and page 0–100 on what is MECHANICALLY checkable' with a specific list of checks. It distinguishes itself from siblings by excluding scratch-marked records and referencing cleanup_scratch, and clarifies that 100 does not mean 'well designed' – a key scope distinction.

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 provides context on when to use the tool (for mechanical scoring) and when not to (scratch records go to cleanup_scratch). It also explains the loop discipline 'score, improve, re-score, and only update_baseline=true after a verified improvement', which guides the agent on when to set the baseline parameter. However, it does not explicitly compare with validate_portal or other similar validation tools, so alternatives are only partially addressed.

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 adds material behavioral detail beyond the annotations: the coverage verification ('staged counts are checked against live listings'), the rollback caveat, and the prerequisite 'Requires PORTAL_VC_DIR.' It aligns with readOnlyHint=false and idempotentHint=false, and does not contradict any annotation. It goes beyond the basics expected for a mutation tool.

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

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

The description is dense but efficient, front-loading the core action ('Export every content resource... AND commit') before adding usage timing and behavioral caveats. Every sentence carries distinct value, though it could be broken into clearer sentences for readability. It is not verbose enough to warrant a 3, but not as crisp as the two-sentence example for a 5.

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

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

For a complex export/commit tool with multiple resource kinds and a coverage check, the description covers the essential facts: what is exported, when to use it, the verification mechanism, and the required environment variable. It doesn't describe return values, but there's no output schema. The missing 'message' parameter usage is covered by the schema, so the description is sufficiently complete for an agent to decide when and how to call it.

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

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

Schema coverage is 100% for the single optional 'message' parameter, which the schema already documents ('Commit message (default: 'snapshot')'). The description does not add any new meaning for this parameter, so the baseline of 3 is correct. The mention of PORTAL_VC_DIR is an environment variable, not a parameter, and doesn't enhance parameter understanding.

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 ('Export'), resource scope ('every content resource... AND datasources'), and destination ('version-control repo and commit'). It clearly distinguishes itself from sibling tools like vc_status or vc_diff by describing a distinct snapshotting action, leaving no ambiguity about what this tool does.

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 provides explicit timing guidance ('Run once to seed history, or anytime to capture a checkpoint'). While it doesn't name alternatives or state when not to use it, the context is clear enough that an agent can choose this tool for snapshot creation without confusion. A 5 requires explicit when-not/alternatives, which is absent, so 4 is appropriate.

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

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

Annotations only declare readOnlyHint=true, but the description goes far beyond by detailing that it runs the same authoring rules without writing, returns a structured { valid, errors, warnings } object, and previews grandfathering behavior. It also enumerates specific footguns it detects, which is exactly the kind of behavior that annotations alone don't convey.

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

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

The description is dense but every sentence earns its place: it front-loads the core purpose and then layers on behaviors like returned shape, grandfathering, and file-preference guidance. Formatting with em dashes and line breaks keeps it readable despite the length, and no information is redundant.

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

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

For a validation tool with no output schema, the description covers return shape, side-effect-free guarantee, the difference between validation and update behavior, and even hints at security/correctness concerns. It also guides on resource loading (file paths and root containment). The focus on this tool's specific role in the portal authoring flow makes it complete 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, but the description adds significant value beyond the schema: it explains trade-offs (e.g., html_file 'byte-exact' and 'PREFER THIS over inlining'), clarifies relationships (html_file vs json_data.html), and provides a detailed example for ui_queries with notes on update semantics. This goes well beyond restating the schema.

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

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

The description opens with a specific verb-resource pair ('validate a block payload') and immediately distinguishes it from siblings by referencing 'the same authoring rules as create_block/update_block'. It clarifies the key non-write behavior and names the exact sibling operations, making the tool's role unmistakable.

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 tells when to use this tool ('Use it to iterate on HTML/JS/CSS until it's clean') and explains the comparison to update_block via against_block_id, including how it interacts with grandfathering. It sets expectations about what will be flagged and contrasts with update_block's warning behavior, giving clear guidance on tool selection.

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

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

The description discloses the full scope of the sweep (all listed resource types), the categories of issues (structural malformations, dangling references, unscoped mass-write SQL, datasource hygiene), and the 'Fixes nothing' behavior. It also mentions that with the limit param, 'still reports the full counts' (though not in the description text, the behavior is implied by the schema's description). This aligns perfectly with the readOnlyHint annotation and adds substantial context beyond it.

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

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

The description is a single dense paragraph that front-loads the action and then enumerates checks. It is information-rich without rambling, but slightly long. Every clause adds value — no filler. It's concise enough given the complexity of the tool.

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

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

The description covers the resource types, the issue categories, and the non-destructive nature. It implies a report of issues and mentions that counts are still reported even when limited. There is no output schema, so the description should clarify return format; while it doesn't specify the exact structure, it's clear enough for an agent to expect a list of findings. The breadth of checks is well covered.

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 only parameter, limit, is fully documented in the schema with a clear description ('Cap the number of issues returned (still reports the full counts). Omit for all'). The tool description adds no additional semantic detail beyond what the schema already provides. Since schema coverage is 100%, 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: 'Sweep every page (layout), partial, theme, query, block, db_modification and system record' — clearly a validation sweep. It enumerates the types of issues it catches, distinguishing it from siblings like validate_block (which is narrower) and repair_query_metadata (which fixes). The purpose is unambiguous and non-tautological.

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

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

Explicit guidance is given: 'run it after bulk changes or on a schedule to catch latent breakage before users do.' It also states 'Fixes nothing,' implying it's for detection rather than remediation. It doesn't explicitly exclude scenarios or name alternative tools, but the context is clear enough for an agent to decide when to invoke it.

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