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

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, but the description adds valuable behavioral context: it explains that binding populates queryResults, preserves html/css/name, and that auto-created queries are linked. It also discloses the rejection condition (missing datasource) and the dry_run behavior. This goes beyond the annotations, though it doesn't detail side effects like whether existing ui_queries are overwritten or how the portal handles failures.

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 well-structured: it opens with the core purpose, then explains the two binding modes, and ends with a critical constraint. Every sentence adds information without redundancy. The parameter details are left to the schema, keeping the description focused.

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 (6 parameters, two mutually exclusive modes, auto-creation behavior, and a rejection condition), the description covers the essential usage scenarios. It doesn't explicitly state what happens to existing ui_queries or how the response looks, but since there's no output schema and the tool is a mutation, the description provides enough for an agent to call it correctly. The missing details are minor and could be inferred from the schema.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by clarifying the relationship between query_id and datasource_id (mutually exclusive), explaining the default behavior of page_size (null = ALL rows, preferred) and the implications of setting a cap, and noting that sql is only used with datasource_id. This enriches the schema's basic 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 clearly states the tool's purpose: 'Give an existing block its data binding so currentBlock.queryResults[0] is populated.' It specifies the resource (block) and the action (bind to a datasource/query), and distinguishes it from siblings like create_block and update_block by focusing on data binding rather than block creation or general updates.

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 explicit usage guidance: it explains the two mutually exclusive options (query_id vs datasource_id), notes that datasource_id auto-creates a SELECT * query, and warns that the bound query must have a datasource or the portal rejects it. It also mentions the dry_run option for previewing without writing, which helps agents decide when to use 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 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 readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate safety. It adds valuable behavioral context: it proves credentials work, reports failure reason and fix, and returns a few short fields rather than a JSON wall. This goes beyond the annotations by describing the failure reporting and response format, which is useful for an agent.

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 'START HERE' directive, immediately establishing the tool's role. Every sentence adds value: the first states the purpose and scope, the second explains the credential proof and failure handling, and the third clarifies the response format and when to use an alternative. No wasted words.

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

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

For a zero-parameter tool with readOnly and openWorld annotations, the description is complete. It covers what the tool does, what it returns, when to use it, and when to use an alternative. The absence of an output schema is mitigated by the description's clear statement of the returned fields. 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 tool has zero parameters, so the schema provides no parameter documentation. The description compensates by explaining what the tool returns (portal, version, user, write permissions, browser assist status) and how it behaves (single round-trip, failure reporting). Since there are no parameters to document, the description effectively covers the tool's semantics.

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

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

The description clearly states the tool's purpose: confirm in one authenticated round-trip which Zuar Portal this folder is on, its version, who you're signed in as, what you may write, and whether browser assist is on. It uses a specific verb ('confirm') and resource ('portal connection'), and distinguishes itself from get_capabilities by noting it returns a few short fields rather than a full JSON wall.

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 'START HERE' and instructs to call get_capabilities only if the full tool/group, VC and audit posture is needed. This provides clear when-to-use guidance and names the alternative tool, making it easy for an agent to decide between check_connection and get_capabilities.

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?

Discloses key side effects: writes config, pins to portal identity, refuses overwrite unless overwrite=true, writes to version control, stores secrets locally and never echoes them. Also explains the security restriction that write-safety toggles are only available via browser, preventing agents from widening permissions. This is exceptionally transparent 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 description is long but information-dense. It front-loads the core purpose and then explains the flow. Some redundancy exists (e.g., repeated mention of browser fallback), but overall each sentence contributes to understanding. Could be slightly tightened, but acceptable for a complex 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?

Given the tool has 22 parameters, no output schema, and complex side effects (browser interaction, security constraints, version control, fallback behaviors), the description is remarkably complete. It covers all major behaviors, prerequisites, security notes, and interaction flows, leaving the agent well-informed.

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%, but the description adds meaningful context: explains ui default, that api_key skips the prompt, density default, and how the browser path differs from args. It doesn't enumerate every parameter but gives enough to understand their roles, especially the security implications of the ui argument.

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: 'Connect THIS portal to a project folder.' It specifies the verb 'connect/configure' and resource 'portal/project'. It distinguishes itself from sibling tools like update_config by focusing on initial configuration and browser-based setup, but doesn't explicitly differentiate from all 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?

Provides clear guidance on when to use the browser UI vs headless mode, explains fallback behavior, and mentions the flow after configuration (points to design_intake). It doesn't explicitly mention alternatives like update_config for later changes, but the primary usage context is well covered.

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

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

Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the create operation is clearly not read-only. The description adds important behavioral nuance: it warns that the legacy 'data' field is ignored by current portal versions, explains that ui_queries is how data binding works and that update_block preserves existing ui_queries, and clarifies that dry_run only reports without creating. It doesn't cover all failure modes or side effects, but given the annotations already flag non-read-only and non-idempotent, the added context is strong and not contradictory.

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 description is dense and front-loaded with the action, type constraint, and guide reference. However, it is long and packs multiple instructions (equivalence to create_resource, structural gates, dry_run) into a paragraph, and parameter-level guidance is spread across the schema. The information is valuable, but the main description could be more scannable. Still, 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 an 11-parameter tool with 100% schema coverage, no output schema, and nested objects, the description covers prerequisites (reading guides), equivalent alternatives, parameter semantics with examples, and caveats about deprecated fields. The agent has enough to call it correctly without external guesswork. The inclusion of update_block behavior adds forward-looking completeness.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond field names: it explains the legacy nature of 'data' (ignored, kept for backward compat), provides a practical example for ui_queries with a full JSON object, explains the mutual exclusivity and byte-exact reading of css_file and html_file, and notes root containment. This goes well beyond the schema's terse descriptions.

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

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

The description states a clear verb and resource ('Create a new HTML block'), explicitly notes the type is always html, and distinguishes it from the generic create_resource while also mentioning the typed alias. It names the related sibling update_block for updates, helping an agent differentiate create from modify 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 directs the agent to read zportal://guide/* resources first for correct authoring, mentions dry_run for previews, and clarifies that this is equivalent to create_resource with a typed schema, and that structural and referential gates run either way. It also recommends preferring html_file for large content and notes ui_queries is the proper binding mechanism, providing clear selection and 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 already indicate readOnlyHint=false and destructiveHint=false, but the description adds crucial behavioral context: writes are gated by risk domain, and there is a dry_run parameter to test without creating. This enriches the agent's understanding of the tool's behavior beyond what annotations convey. However, it does not explicitly mention idempotency (which the annotations say is false) or what happens on validation failure, but the dry_run mention partially covers the validation aspect.

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, both packed with essential information. It front-loads the core action and then immediately gives the most critical usage constraint (write gates). No filler words. Perfectly sized.

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 (three params, one with enum, nested body, write gating), the description covers the key aspects: what it does, how to use it (dry_run), and when it's allowed. It lacks explicit return format, but there is no output schema, so the description should ideally mention what the response contains. However, the description's mention of 'report the would-be write' for dry_run gives some hint. It also doesn't list which resources are admin vs data, but that's covered by the environment variables. Overall, nearly 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?

The schema provides descriptions for all three parameters (body, dry_run, resource), with resource having an enum and clear description. The description adds value by explaining that `body` carries fields and that dry_run runs all gates, but largely repeats what the schema says. Since schema coverage is 100%, the description doesn't need to add much, but it does provide a little extra context about the write gates.

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 ('Create') and the resource ('record'), and mentions that `body` carries the resource's fields. It distinguishes from siblings like create_block and update_resource by being a generic create. However, it does not explicitly differentiate from create_block, which could be a specific case of 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 explicitly states the gating conditions by risk domain: content writes are on by default, while data and admin writes require specific environment variables (PORTAL_ALLOW_DATA_WRITES, PORTAL_ALLOW_ADMIN_WRITES). This tells the agent when it can and cannot use the tool, and implies that for admin/data resources it may need to check permissions first. It also references describe_resource for details, which is helpful.

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 mutation is known. The description goes beyond by detailing refusal conditions (dependent records, last admin, own account) and the force override effect. It also mentions the restore capability, adding useful context. However, it does not explain the error format or what happens on successful delete (e.g., return value), but given annotations, this is adequate.

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 key usage conditions front-loaded. It includes important exclusions and alternatives without fluff. Slight deduction for being dense but not overly long; 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 complexity (5 params, enums) and the absence of an output schema, the description covers the critical usage semantics: confirmation, force, dry_run (via get_references), and resource type. It mentions describe_resource for fields, which helps. It lacks details on return values, but that's not required if no output schema. Overall, it is fairly complete for a 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% and each parameter has a description in the schema. The description adds minimal extra: for id, it mentions 'or name, for tags' which is not in the schema. Other parameters are already well documented. Baseline 3 is appropriate as the schema carries most of the 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 clearly states the action: 'Delete a record by id (or name, for tags)' with the resource type parameter. It distinguishes from siblings like restore_resource and get_references by mentioning them. The verb 'delete' is specific and the resource scope is explicit.

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

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

The description provides explicit conditions for use: requires confirm:true, same write gating as create_resource, and names alternatives (restore_resource for content records, get_references for viewing dependents). It also clarifies when force=true is appropriate and what it does. This is thorough routing guidance.

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

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

With 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 provide readOnlyHint=true, which matches the described posture reporting. The description adds behavioral traits beyond that: redacting secrets, remaining available when other groups are gated, and reporting write-safety posture. It doesn't contradict annotations. Slight deduction because the tool itself is a read operation, but the additional value is significant.

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, listing a lot of content in a single flowing sentence, then two short punchy sentences for the 'run it before acting' and redaction hints. Every clause adds value; front-loaded with what it does. 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 zero params and a rich natural-language spec of the response contents (portal URL, user, config file, vc status, browser-assist, audit log), the description is complete. No output schema exists, so the description compensates by itemizing the report's contents. Nothing omitted that an agent needs to call it correctly.

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

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

With 0 parameters and 100% schema coverage, the baseline is 4. The description doesn't add parameter details (none exist), but it enriches the purpose of the no-params call by listing what the response will contain, which helps the agent anticipate output. No loss.

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?

Description states precisely what the tool reports: enabled tool groups/tools, posture, config, vc status, browser-assist flag, audit logging. Identifies itself as 'THE orientation call' and enumerates distinct content areas, clearly distinguishing it from siblings like get_config, get_version, or check_connection.

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 'run it before acting' and notes it 'stays available even when other tool groups are gated off.' This provides clear when-to-use guidance and implies it should be the first call. No exclusion needed since no alternative tool fulfills this orientation role, and the description effectively differentiates 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 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 description doesn't need to restate that. It adds valuable context: metrics are in-memory and reset on process restart, and it explicitly states no payloads or secrets are included. This goes beyond the annotations by disclosing the ephemeral nature of the data and the scope of what's reported.

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. It lists the metrics in a compact list, adds the metadata-only caveat, notes the reset behavior, and ends with a usage recommendation. Every sentence adds value with no redundancy.

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

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

For a parameterless, read-only tool with no output schema, the description is complete. It covers what metrics are reported, the scope (this server process), the ephemeral nature, and the intended use case. An agent has everything needed to decide when to call it and what to expect.

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

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

The tool has zero parameters, so the schema provides no parameter documentation. The description compensates by explaining what the tool reports and its scope, which is sufficient for a parameterless tool. The baseline for 0 params is 4, and the description meets that by clearly explaining the tool's output.

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 reports in-memory observability metrics for the server process, listing specific metrics (per-tool call count, error count/rate, latency, uptime, circuit-breaker state). It distinguishes itself from siblings by focusing on observability rather than configuration or resource management.

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 to use it: 'Use it to spot a failing tool or a degraded portal upstream.' It also clarifies what it is not for: 'Metadata only — no payloads or secrets.' This provides clear guidance on when to invoke this tool versus 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 the description reinforces this with 'Read-only dependency query'. It adds valuable behavioral context beyond annotations by describing both directions, the dangling reference flag (`exists:false`), and its relationship with the delete gate. This meaningfully extends what the 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?

The description is concise but information-dense. The first phrase 'Read-only dependency query' establishes intent upfront, and the rest explains behavior without redundancy. Every clause adds useful details: both directions, breakage semantics, examples, and use cases.

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 rich annotations, fully documented input schema, and the presence of an output schema, the description covers everything an agent needs to select and call this tool correctly. It explains the main use cases and the meaning of the returned fields without relying on external documentation.

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%, so the schema already documents both `id` and `resource`. The description adds context around the kind of record (e.g., datasource, query) but does not explain parameter specifics 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 states a specific verb ('query'), a precise resource ('a record'), and clearly defines the two result categories (`dependents` and `references`) with concrete examples. This distinguishes it from sibling tools like get_rules or find_resource by showing exactly what the tool returns.

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 tells when to use it: before a delete/rename or to trace usage of a datasource/query. It also frames the dependents list as 'the same analysis the delete gate runs', which communicates a clear purpose and context where this tool is the right choice.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate safety. It adds significant behavioral value by explaining how the summary mode transforms bulky fields into size stats, including a concrete example (block drops ~2,750 → ~150 tokens). This goes beyond the schema by revealing the token-cost impact, which is not visible from the annotations or schema. The description doesn't contradict 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 concise, well-structured, and front-loaded with the core purpose. The token-cost guidance is placed after the main action, making it easy to scan. Every sentence adds value, with no redundant filler. The example of token reduction is a high-impact detail delivered efficiently.

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 fetch tool with 4 parameters, the description covers the key decision points: how to control token cost via summary and fields, and the id vs name distinction for tags. The output schema is absent, so the description should clarify what the return value looks like; it does partially by describing summary and fields outputs. However, it doesn't mention error cases or how to know which resource types support name-based lookup, but given the complexity and the schema's completeness, this is adequate.

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's description coverage is 100%, so every parameter is documented there. The description adds some extra meaning by explaining how 'fields' and 'summary' interact (e.g., fields returns only top-level fields plus id, summary returns overview with size stats). However, it doesn't fully clarify the relationship between summary and fields (e.g., can they be combined?), which is a limitation. Still, given high schema coverage, a baseline of 3 is appropriate, with modest increments from the added context.

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'), a resource ('a single record of a resource'), and identifies the key identifier ('by its id'). It also notes the special case for tags (name instead of id), which adds clarity. This clearly distinguishes it from sibling tools like list_resource and find_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 explicitly explains when to use the summary and fields options to control token cost, and implicitly guides the choice between the full record versus cheaper variants. It contrasts with potential alternatives by focusing on fetching a single record versus listing or finding, though it doesn't explicitly name alternative tools. However, the guidance on option selection is strong, and the context is clear enough.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate safety. It adds valuable behavioral context: comment/string-aware scanning, classification of blocks, mapping through layouts/partials/snippets, and the fact that it executes queries (which is a side-effect despite read-only intent). It also discloses that it returns a browser-probe checklist, which is beyond the schema. Minor deduction: it doesn't explicitly state that executing queries may have performance implications, but the read-only annotation covers the safety profile.

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 most important usage guidance ('run BEFORE writing any conversion pattern'). Every sentence adds substantive detail about scope, coverage, and behavior. It's long, but the complexity of the tool justifies it. Slight deduction for being a wall of text without paragraph breaks, which could be structured better.

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 audit tool with 3 optional parameters, 100% schema coverage, and read-only annotations, the description covers everything an agent needs: what it audits, how it classifies, what it flags, how it handles queries, and what it returns (including the browser-probe checklist). No output schema exists, so the description's mention of return contents is essential and sufficient. Nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters well. The description adds context by explaining the trade-off between structural-only and full preflight (via execute_queries), and clarifies that limit caps per-block detail entries while full counts are always reported. This goes beyond the schema's terse descriptions, so a 4 is warranted.

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 ('run') and resource ('migration preflight probe'), and clearly distinguishes it from siblings by emphasizing it is an empirical audit that covers every block by function, not just scripted ones. It names the sibling repair_query_metadata as a fix for stale metadata, which helps differentiate.

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 'run BEFORE writing any conversion pattern', giving a clear temporal usage condition. It also implies when not to use it (when you need to fix stale metadata, use repair_query_metadata instead) and contrasts with structural-only passes via the execute_queries parameter. This is strong 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 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?

Annotations declare readOnlyHint:false, destructiveHint:false, idempotentHint:true. The description reinforces these honestly (no contradiction: dry_run writes nothing, replace doesn't destroy blocks, merge is repeatable) while adding genuinely new behavioral disclosure beyond annotations: auto-stack fallback, clipping when Σ(heights) exceeds budget, preservation of optimized geometry, and the overflow field in the response. It even warns about parallel-loop conflicts via expected_updated_at. No hidden surprises are left implicit.

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 and information-rich — it earns its length with concrete values (50% default, budget guide, step sizes of 25), and it front-loads the most important facts (atomicity, mode semantics) before the budget guide. It loses half a point for length: at 700+ words it's on the edge of what a description should hold, and a few items (e.g., the within-paragraph 're-read, re-apply, retry') could be trimmed without loss. Still, structure is excellent: every sentence adds information and the flow from purpose → modes → edge cases → budgets → fallback plan is logical.

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 this complex (7 params, 2 modes, atomic RMW, geometry placement, budget constraints, concurrency), the description is thorough: it covers failure modes (clipping), feedback (overflow in response), preview (dry_run), checked confirmation for destructive replace, and forward-migration guidance (raise grid height via update_resource). The schema's own text (descriptions on blocks, position, etc.) carries its weight, but the description doesn't rely on it — everything an agent needs to call place_blocks safely and effectively is within reach. Output-schema absence is not a gap here.

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 each parameter individually. The description adds meaningful cross-parameter interactions (position+height precedence rules, 'an entry with NEITHER position NOR height keeps an already-placed block's current geometry', auto-stack ordering) that give value beyond the schema. The grid-budget guidance (e.g., 'filter bar 8-10, KPI band 18-22, chart card 30-35, table 35-40') is excellent proactive guidance, though the schema already covers some of this, so this is a strong 4, not quite a 5 (which would be reserved for a tool whose schema did none of this).

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 crisp verb+resource statement ('Declaratively manage which blocks a page (layout) shows, in ONE atomic read-modify-write') that immediately conveys both function and scope. It explicitly names its own boundaries with sibling guidance integrated inline: 'Blocks are placed, not created (create_block first) and never deleted (delete_resource does that).' An agent could select this tool without ambiguity among 40+ 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?

Every non-obvious behavior is scoped to exact mode semantics: merge = upsert/remove only; replace = page becomes EXACTLY the list (confirm:true required). The description also covers edge cases (preservation of grid.layouts, hidden flags, geometry of surviving blocks) and names the sibling tools that own related concerns (create_block, delete_resource, update_resource, dry_run preview). An agent could decide when to branch to mode=replace vs merge with no further help.

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?

Annotations already declare idempotentHint=true and destructiveHint=false)Skip; the description adds behavioral context: it resets the HTTP session DNS, drops caches, and notes tool-surface gating requires a server restart. This goes beyond annotations and warns of a side effect (session reset) that agents need to know, without contradicting structured hints.

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 core action (drop caches and re-read) and then adds usage context. Every sentence provides a distinct piece of info (what resets, when to use, auto-load caveat, restart requirement). Slightly long but each part earns its place.

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

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

With no parameters and no output schema, the description must stand on its own. It explains the full behavior (cache drop, re-read from disk, session reset), when to call it, and the automatic pickup nuance. It doesn't spell out the return value, but for a side-effecting reload tool that is acceptable. Complete for its complexity.

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

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

There are zero parameters, so the input schema provides no semantics to extend. The description correctly avoids inventing parameters and instead documents the tool's behavior and the conditions for its use, which is the appropriate compensation.

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 (drop caches, re-read config), names the specific config sources explicitly (.zuar-portal/config.json, bundle config, env-derived settings), and clearly distinguishes it from a passive load or update. It also mentions resetting the HTTP session, which differentiates it from get_config/update_config siblings.

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

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

Explicitly states when to use (after manually editing config) and what is auto-picked-up (mtime-aware automatic reload for existing files). It identifies the triggering condition for a newly created config file or bundle/env change, giving clear use cases. It does not name alternatives like get_config, but the guidance is sufficient for an agent to decide.

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 idempotent and non-destructive; the description adds depth: re-sends other fields verbatim, dry-run by default, apply:true required to write, round-trip verification, and version-control mirroring. 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?

Three sentences, each serving a distinct purpose: action, rationale, behavior. It's front-loaded and efficient, though slightly dense; a minor tightening would make it 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?

Complete for an agent: explains what it does, when to use it, how to invoke the write (apply:true), and what to expect (diff report, write verification). Lacks explicit output schema but the description provides 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 covers all 3 params with descriptions, so baseline is 3. The description adds value by clarifying the dry-run semantics of apply (default false) and that params is for parameterized queries, enhancing 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?

Clearly states the action (re-introspect and store column metadata) and the resource (saved query), and explicitly enumerates what it does NOT touch (SQL, datasource binding). This scoping differentiates it from sibling tools without naming them.

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

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

Provides a concrete trigger condition (migration_preflight flags stale metadata) and explains the dry-run/apply workflow. It implies when not to use it (when you need to change SQL or datasource) but doesn't explicitly name 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?

Beyond annotations, the description reveals that the restore writes through the gated write path, is itself committed, recreates DELETED blocks under their old id, and requires PORTAL_VC_DIR. It also defines the open-world boundary by naming never-snapshotted record kinds. This 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 core action is front-loaded, and every clause adds useful detail: side effects, prerequisites, source of ref, and exclusions. Despite its density, there is no redundant text, making it appropriately sized for the tool's complexity.

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

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

For a mutation tool with no output schema, the description covers prerequisites, side effects, ref sourcing, and unsupported resources. The only notable omission is the return/response behavior, which the absence of an output schema leaves to inference.

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

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

The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds operational meaning by explaining the default ref behavior ('the version before the latest change'), pointing users to vc_log for valid refs, and clarifying datasource requirements.

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 ('revert... to a prior committed version'), the target resources ('content record or a datasource'), and the write-back effect. This clearly distinguishes restore_resource from inspection siblings like vc_diff and vc_log.

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

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

It gives explicit when-to-use guidance: omit ref to undo the latest change, or pass a commit hash from vc_log after inspecting with vc_diff. It also names prerequisites (PORTAL_VC_DIR, data writes enabled for datasource) and lists unsupported resource types, which tells an agent when not to use the tool.

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

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

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?

Even with annotations indicating destructive and idempotent behavior, the description adds critical specifics: FULL REPLACE semantics, omitted lists untouched, the exact environment variable, the confirm flag requirement, dry_run capability, and safety guard against self-lockout. It goes far beyond what annotations provide, explaining exactly what happens to each portion of the access definition.

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 efficient sentences carry all the essential information: the action, the semantics, and the safety requirements. It is front-loaded with the most critical behavior (FULL REPLACE) and uses the second sentence for critical constraints. The only minor issue is the typo 'PORTALLOW' instead of 'PORTAL_ALLOW', which could cause confusion but does not detract from overall clarity.

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

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

For a destructive, write-operation tool with 6 parameters and no output schema, the description covers all the key behaviors an agent needs: replacement semantics, requirements, dry run, and self-lockout protection. It doesn't explain return values, but that is absent from annotations yet likely not essential given the operation-focused nature. The safety and idempotency aspects are sufficiently addressed. The description is both complete and safe.

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 has 100% parameter description coverage with each parameter clearly documented (e.g., 'Complete list of group ids... full replace'). The description adds value by synopsizing the relationship between groups and permissions and clarifying the interaction with confirm and dry_run. It slightly exceeds the baseline by clarifying the high-level contract, though the schema already does most of the heavy lifting.

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

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

The description clearly states the tool replaces a user's group membership and/or permission set, using the strong verb 'Replace' and the resource (user's access). It distinguishes itself from read-only siblings like get_user_access by explicitly framing it as a mutation. The core behavior of full replacement is front and center, making the tool's purpose immediately obvious.

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 strong usage context: requiring admin writes (PORTALLOW_ADMIN_WRITES=1) and confirm:true, plus explaining dry_run for safe preview and self-lockout protection. It clearly implies when to use this tool (to change access) versus alternatives through its explicit scope. However, it does not explicitly name a sibling tool for comparison or state when NOT to use it, so it misses the highest tier.

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?

The description goes beyond annotations by explaining side effects: it fetches the website (SSRF-guarded) only to suggest colors, and it explicitly states it does not create anything. This aligns with the readOnlyHint and provides transparency about the fetch operation and the purpose of generating a spec. It also clarifies the relationship with create_resource without overstepping.

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 overly verbose. It includes a full example of a create_resource call, mentions VC-tracked content write, and references the design_intake PROMPT—details that are not necessary for understanding the tool's core function. The first sentence is clear, but the subsequent expansion dilutes the message and could confuse an agent.

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 workflow (fetch, suggest, generate spec, then create) and clarifies that the output is a spec for use with create_resource. It also notes the SSRF guard. However, it does not mention the output format or how the spec is returned, which could be a gap for agents that need to consume the result. Still, given the schema covers params, the description is largely 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?

While the schema already documents each parameter thoroughly (100% coverage), the description adds meaningful relationships: it explains that website_url is fetched only when primary_color is omitted, and that brand_name is used to name the theme. However, it does not elaborate on all params (e.g., font, mode), but the schema descriptions already handle those, so the additional context is beneficial.

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: 'Turn brand preferences into a portal theme spec' and explicitly notes it does not create anything. This is a specific verb-noun pair that distinguishes it from a creation tool, and the no-write intent is reinforced by the readOnlyHint annotation.

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 a workflow (fetch site, suggest colors, then create via create_resource) but does not explicitly state when to use this tool versus alternatives. It mentions the design_intake PROMPT but does not provide clear conditions or scenarios for invocation. More explicit guidance such as 'use this when you need to generate a theme spec' would improve clarity.

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 mutation (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description adds valuable details beyond annotations: server-side field merging, delta-only validation with grandfathering of existing violations, and dry_run preview behavior. It does not mention error handling, authentication, or rate limits, but what it adds is meaningful and non-redundant.

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, front-loaded with the core action and followed by key behavioral highlights. It is efficiently structured with no fluff, covering merge semantics, validation behavior, and dry_run in a compact form. 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 (14 parameters, nested objects) and lack of an output schema, the description covers the main behavioral aspects (merge, delta validation, dry_run) and points to the schema for parameter details. It does not mention the return value or error behavior, but the absence of an output schema makes it acceptable to rely on the schema for parameters. Overall, it is sufficiently 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?

The schema description coverage is 100%, and each parameter is already well-documented (e.g., ui_queries, dry_run, merge_tags, html_file). The description summarizes overall behavior (merge, delta validation) but does not add per-parameter meaning beyond the schema. It also clarifies the omission semantics of ui_queries, but that is already present in the schema. Therefore, it meets the baseline of 3 but does not exceed it.

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 ('Update an existing HTML block by UUID') with a clear resource and identifier. It distinguishes itself from sibling create_block (which creates) and generic update_resource by targeting HTML blocks and using UUIDs. This is precise and 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 provides clear context for use: updating an existing HTML block via UUID, with merge semantics and a dry_run option. However, it does not explicitly mention alternatives or when to choose this over other update/create tools, so it lacks explicit exclusion guidance but still offers strong contextual cues.

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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds significant behavioral context: it explains the write requires confirm=true, the dry_run behavior, the merge vs replace semantics, and the revert mechanism via previous_at_path. It also discloses that invalid references are refused. This goes beyond the annotations, which are sparse, and provides the agent with critical safety and operational details. The only minor gap is not explicitly stating that the tool is idempotent, but the description's mention of merge and revert implies 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 paragraph but packs a lot of information. It front-loads the core action ('Set a value at a config path') and then covers key behaviors. It's not overly verbose, but it could be slightly more structured (e.g., bullet points) for readability. However, every sentence earns its place, and the information density is high without being 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?

Given the tool's complexity (5 params, conditional write behavior, revert mechanism), the description covers the essential aspects: prerequisites, dry_run, merge, revert, and error conditions. There's no output schema, so the description's mention of previous_at_path is crucial. The only minor omission is not specifying the exact response format beyond previous_at_path, but that's acceptable given the tool's nature. Overall, it's complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the relationship between parameters: confirm must be true for writes, dry_run previews without writing, merge modifies behavior, and the response includes previous_at_path for revert. It also clarifies the path format (array of strings) and gives an example. This is more than the schema provides, so it earns a 4 rather than a baseline 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 clearly states the tool's purpose: 'Set a value at a config path.' It specifies the resource (portal config) and the action (set/update), and distinguishes it from siblings like get_config and update_resource by focusing on config path manipulation. The description also mentions specific config keys (default_dashboard/theme_id) and the merge behavior, which adds specificity beyond the name.

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 explicit conditions for use: requires admin writes enabled (PORTAL_ALLOW_ADMIN_WRITES=1) AND confirm=true, and mentions dry_run for previewing. It also notes that pointing at a missing record is refused, which is a clear constraint. While it doesn't explicitly name alternatives, the context of portal config vs resource updates is implied, and the conditions are specific enough to guide when 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 contain no safety flags (readOnlyHint=false, destructiveHint=false) and no concurrency hints. The description compensates fully: it discloses the merge semantics (only body fields change, untouched preserved), the write gating similarity to create_resource, the optimistic-concurrency behavior with conflict refusal, the dry_run behavior (runs gates, reports merged body without writing), and statement that unknown fields are dropped. This goes well beyond the annotations and is critical 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 three sentences, dense with information, and each sentence earns its place. Key operational guidance (merge vs full-replace, concurrency token) is front-loaded. No fluff, no repetition of schema. This is appropriately concise for a complex mutation 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?

Given 5 parameters, no output schema, and rich semantics (merge, concurrency, dry_run), the description covers everything an agent needs: what the call does, how the merge works, how to avoid lost updates, what dry_run does, and the write gating. The sibling list helps the agent route to describe_resource for field details, which is referenced in the schema enum. No critical gaps are evident.

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 5 parameters. The description adds value beyond the schema by explaining the semantics of expected_updated_at (conflict refusal) and the merge behavior of body, which the schema only describes as 'Fields to change. Unknown fields are dropped.' The description clarifies the partial-update intent. This earns above baseline 3, but not 5 because the description doesn't add much about dry_run beyond the schema's 'Run every gate... without writing.'

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 ('Update'), a resource ('a record by id'), and critically distinguishes partial update from the portal PUT full-replace behavior. It also names a sibling (create_resource) for write gating. This clearly differentiates from update_block/update_config and the read 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 when to use the optimistic-concurrency token (expected_updated_at) for loop/parallel safety, mentions the same write gating as create_resource, and contrasts with portal PUT full-replace. It provides clear context and an exclusion (portal PUT does NOT do partial merge), which helps the agent choose this over 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 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.

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

Annotations already mark readOnlyHint=true, so the description adds value beyond that by explaining the default ref behavior (ref_b=HEAD, ref_a=previous commit) and the requirement for PORTAL_VC_DIR. It also notes that the file list is always complete even when max_chars caps the diff text. 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 three sentences, front-loaded with the core purpose, then defaults, then a usage warning and environment requirement. Every sentence earns its place with no redundancy.

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

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

Given the output schema exists and annotations are present, the description covers the key behavioral aspects: two scoping modes, default refs, the pre-restore use case, and the PORTAL_VC_DIR dependency. It doesn't enumerate potential errors or return structure, but the output schema handles that, and the description is otherwise complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining how ref_a/ref_b defaults are calculated, that passing hashes from vc_log enables arbitrary pairs, and that max_chars caps diff text while the file list remains complete. This enriches the parameter understanding 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 produces a unified diff between two committed versions, and distinguishes between scoping to a single record or the whole repo. It is differentiated from sibling tools like vc_status (status) and vc_log (log) by focusing on diffing commits.

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 this tool, specifically advising to inspect the diff BEFORE restore_resource. It also mentions passing hashes from vc_log, implying vc_log is the source for refs. It lacks explicit exclusions or a named alternative for 'when not to use', but the usage guidance is solid.

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=true annotation already declares safety, so the description adds value with the PORTAL_VC_DIR prerequisite and the fact that a returned hash can be used with restore_resource. It does not describe ordering, error behavior, or concurrency, but the annotation lowers the burden and the added requirement is useful context.

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

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

Two sentences carry all essential information: what the tool does, optional scoping, integration with restore_resource, and a required environment variable. The most important verb is front-loaded, and there is no filler.

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

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

For a read-only listing tool with no output schema, the description covers purpose, scoping, a key output usage (hash for restore), and a prerequisite. It leaves ordering and pagination behavior implicit, but the schema documents the limit parameter and the readOnlyHint covers the safety profile.

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 100% of the parameters, so the description is not required to explain them. It adds minimal semantic value by saying commits can be "optionally scoped to one record," which loosely maps to id and resource, but this is already implied by the 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 states a specific verb and resource: "List recent commits", with an optional scope to one record. It also distinguishes from sibling version-control tools like vc_status and vc_diff by focusing on commit history and explicitly linking to restore_resource via the returned hash.

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, namely to view recent commit history and to obtain a hash for revert via restore_resource. However, it does not explicitly mention when not to use it or name alternatives like vc_status or vc_diff, leaving the comparison to the agent to infer.

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 annotation already marks it safe, and the description adds useful behavior beyond that: every content write is auto-committed and can be reverted via restore_resource. This alerts the agent to causality and reversibility while remaining consistent with the read-only 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 delivers a dense but complete picture in two sentences. Every phrase adds value: the enable condition, the reported fields, and the operational consequence of auto-committing. 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 zero-parameter read-only status tool, this description is complete. It tells the agent what will be reported, how version control is enabled, which environment variables matter, and what behavior follows when enabled.

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 100% schema coverage, so no parameter explanation is necessary. The description correctly focuses entirely on behavior and return meaning rather than inventing input semantics.

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

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

The description uses a specific verb, 'Report', and names precise resources and scope: portal version-control enabled state, repo location, and push configuration. It reads as a clear status command that an agent can distinguish from vc_log, vc_diff, and restore_resource without inspecting those 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 provides clear context: call this tool when you need to know the version-control configuration or understand auto-commit behavior. It does not explicitly name alternative tools or exclude cases, so it stops short of a 5.

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