Layerz

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

Annotations declare destructiveHint=true, and the description adds substantial behavioral context: the 'replace' mode wipes non-default sections, dry_run validates without writing, lagged references return 0 at period 0, and the tool is unavailable for read-only keys. It also explains the merge vs replace semantics and the post-apply workflow (read template guide, update FINANCE.md). This goes well beyond what annotations alone provide, though it doesn't enumerate every side effect of a merge operation.

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

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

The description is information-dense and front-loaded with the core purpose, but it is very long and somewhat sprawling. It covers naming rules, lag suffixes, cross-granularity behavior, template workflow, and list mode in a single block. While every sentence carries useful information, the density makes it harder to scan. A more structured layout (short paragraphs or bullets) would improve readability without losing content.

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

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

For a complex tool with 6 parameters, no output schema, and destructive potential, the description is remarkably complete. It covers the blueprint schema shape, naming constraints, recursion semantics, cross-granularity behavior, template mode, dry-run validation, and the post-apply workflow. It even points to external docs (docs/mdk-format.md, src/core/blueprint-schema.ts) for deeper detail. An agent has everything needed to decide whether and how to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds significant meaning beyond the schema: it explains the blueprint shape in detail (sections, items, roles, lists, mapped_to, timeline_values), the lag suffix syntax for recursion, the stock-flow pattern, and the mutual exclusivity of blueprint and template_id. It also clarifies the summary parameter's role as a version-history label. This is rich semantic context that the schema alone doesn't provide.

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

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

The description opens with a specific verb+resource: 'Build/extend a model from a strict Blueprint.' It immediately distinguishes itself from layerz_patch by stating this is for bulk creation of whole sections with hierarchy, while incremental single-item edits should use layerz_patch. The title 'Build from blueprint' is expanded with concrete detail about what a blueprint contains (sections, items, names, formulas), so the agent knows exactly what this tool does and how it differs from siblings.

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

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

The description gives explicit when-to-use guidance: 'Use this for bulk creation of whole sections with their hierarchy; for incremental edits on a single item or two, prefer layerz_patch.' It also explains when to use template_id instead of blueprint, and notes the tool is 'Not available for read-only API keys.' This is model-level routing guidance that tells the agent exactly when to select 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 indicate readOnlyHint=false and destructiveHint=false, meaning the tool is a non-destructive write operation. The description adds that it creates a resource and returns its UUID, and notes API key restrictions—useful context beyond annotations. However, it doesn't detail behavior like validation side effects or whether templates are required, but given the annotations and the clear creation semantics, a 3 is appropriate.

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 moderately long but well-structured: a clear opening sentence, then a valuable but detailed glyph guidance section. The glyph guidance is somewhat verbose but earns its place given the parameter's complexity. The key usage constraints are front-loaded, and the API key limitation is at the end. Overall efficient, but the glyph list could be more concise.

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

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

The tool has multiple optional parameters (subtitle, timelines, template_id) and no output schema. The description explains the glyph parameter thoroughly and mentions the UUID return, but does not elaborate on timelines structure or template_id usage. However, given that nested objects (timelines) are described in the schema and the required name is simple, the description covers the most critical decision-making context, making it largely complete. A minor gap remains for template_id, but overall the tool can be called 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 low at 20% (only the glyph parameter has a description). The description compensates substantially by explaining the naming conventions and providing domain-specific examples for glyph, which adds semantic meaning beyond the schema. It also hints at the role of name and other parameters, though not each in detail. This elevates the score above the baseline.

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 creates a new financial model and returns its UUID. It is distinct from siblings like layerz_get_model, layerz_patch, or layerz_build_from_blueprint, which involve retrieval or modification. The description makes the 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 provides explicit guidance on when to use this tool, including the type of model to create, suggested glyph choices by business domain, and a clear prevention: 'Not available for model-scoped or read-only API keys.' This exceeds typical usage guidance and directly helps the agent select the tool over alternatives like layerz_patch or layerz_build_from_blueprint.

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 sparse annotations, the description exposes key behaviors: the signed URL is short-lived, the file_id expires after 24 hours, uploads are limited to 25 MB, and only a MIME whitelist is allowed. It also clarifies the upload mechanism and that binary data never enters the agent context, which is valuable behavioral context.

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

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

The description is compact and front-loaded: purpose first, then the upload workflow with a concrete curl example, then limits and expiry. Every sentence contributes actionable information with no filler.

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

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

For a tool with no output schema and minimal annotations, the description supplies all essentials: what is returned (signed_url and file_id), how to use them, size limits, MIME restrictions, expiration, and the required follow-up call. An agent has enough 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 input schema already covers all three parameters at 100%, so the baseline is 3. The description adds meaningful semantics by explaining how content_type is used in the PUT request and by listing the allowed MIME types, going beyond the schema's basic examples.

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: 'Issue a short-lived signed URL to upload an Excel/CSV file straight into Storage.' It also clearly differentiates this from layerz_parse_file by framing parse_file as the downstream step, so an agent knows the tool's exact role.

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 context on when to use this tool: when a file must be uploaded to Storage without entering the agent context, followed by layerz_parse_file. It does not explicitly enumerate when-not-to-use cases or alternatives, but the workflow is unmistakable.

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' destructiveHint, the description reveals that deletion cascades to every input row bearing the dataset_id, which is a material side effect. It also discloses a guard (refusal to delete the default Layer) and an auth constraint (unavailable to read-only keys), all of which are behavioral traits an agent could not infer from the schema or 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 short sentences, each carrying distinct information: the core destructive behavior, the default-layer safety guard, and the API-key restriction. The primary action 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 destructive operation with no output schema, the description covers what is deleted, the condition under which deletion is refused, and who is allowed to call it. The only missing details (e.g., irreversibility) are already signaled by destructiveHint=true.

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 gives no description for the required dataset_id parameter, but the description clarifies its role: it identifies the Layer and the input rows that will be deleted. summary and model_id are already described in the schema, so the description's partial parameter coverage is sufficient.

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 identifies a specific action ('Delete a Layer') and its precise scope ('every input row that carries its dataset_id'), and differentiates from the many sibling tools by naming a destructive delete operation rather than an update, import, or list. The guard about the default Layer and the auth restriction further pin down 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?

The description gives clear context: use this tool to delete a Layer and its associated input rows, not to update or import a branch. It also states explicit when-not conditions—the default Layer is protected and read-only API keys cannot perform the operation—but it never names an alternative tool.

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

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

Annotations already signal destructiveHint=true, and the description goes far beyond that: it specifies what is destroyed (staged transactions, input rows, provenance tags, import entry), what is preserved (items, branch), the refusal condition, the preview requirement, the retry mechanism, and rollback via version restore. This is exemplary behavioral disclosure for a destructive 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 every sentence earns its place: main effect, preservation semantics, refusal/retry flow, and auth restriction. It is front-loaded with the core action and structured so an agent can quickly extract what gets deleted and what requires confirmation.

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 destructive operation with no output schema, the description covers the full invocation lifecycle: preconditions, destructive scope, error/refusal handling, confirmation flag, and rollback path. The only gaps (exact success response shape) are acceptable given the absence of an output 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that confirm_purge is only used after a PURGE_CONFIRMATION_REQUIRED refusal, and it ties connection_id to the data-source context. This goes beyond merely restating parameter names.

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: 'Disconnect a data source (API connector or file import)' and then details exactly what is dropped, purged, and kept. It clearly distinguishes this tool from sibling delete tools like layerz_delete_branch and layerz_delete_mapping by scoping it to data-source removal.

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 contextual guidance: it explains what a disconnect entails, when a purge is refused, and when to retry with confirm_purge. It also states an explicit exclusion ('Not available for read-only API keys'), though it does not name alternative tools for cases where a different deletion operation is needed.

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 destructiveHint=true and readOnlyHint=false. The description adds that deletion is effective only after re-sync ('Re-sync to re-project without it') and that read-only API keys cannot use this tool, which is useful behavioral context beyond the annotations. No contradiction.

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

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

Two concise sentences, front-loaded with the action and resource, followed by the re-sync implication and API key restriction. Every sentence carries meaning and no fluff is present.

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

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

For a destructive tool with full schema coverage and annotations, the description covers the key steps: obtaining the id and the post-delete re-sync requirement. It omits explicit permanence warning, but destructiveHint covers that, and there is no output schema to explain. Slightly more could be said about model_id requirements, but the schema handles 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 description coverage is 100%, so the baseline is 3. The description only references mapping_id via 'from layerz_list_mappings', which the schema already states explicitly. No additional parameter semantics are added beyond the schema.

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

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

States the specific action ('Delete'), the resource ('import classification rule'), and the source of the identifier ('from layerz_list_mappings'), distinguishing it from sibling tools like layerz_set_mapping and layerz_list_mappings. The verb and object are 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?

Gives clear context that the rule id comes from layerz_list_mappings and that a re-sync is needed after deletion. It does not explicitly name alternative tools for creating/modifying rules, but the delete-vs-edit distinction is evident from the tool name and sibling set.

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 the description adds meaningful behavioral detail: what 'precedents' vs 'dependents' mean and that depth controls transitive traversal. It does not describe response shape or pagination, but the read-only safety profile is already covered by annotations.

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

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

One compact, front-loaded sentence defines the core operation, explains the two directions, provides a familiar analogy, and points to scoping parameters. Every clause earns its place with no filler.

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

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

The description covers selection and invocation needs: the graph type, both direction semantics, and how to scope depth and direction. All four parameters are fully documented in the schema, and the read-only annotations cover the safety profile, so the absence of an output schema is a minor gap.

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

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

Schema coverage is 100%, and the description mostly restates parameter behavior ('Use depth for transitive walks and direction to scope') that the schema already documents. The description adds no new parameter syntax or hidden constraints, so the baseline score applies.

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

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

Opens with a specific verb+resource ('Trace an item's dependency graph') and defines both conceptual halves: 'precedents' and 'dependents'. The Excel analogy reinforces the operation, and no sibling tool targets dependency relationships, so it is clearly distinguishable.

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 conveys when to use the tool: for dependency tracing, with explicit pointers to `depth` for transitive walks and `direction` for scoping. It does not name alternative tools or when-not-to-use cases, but no sibling offers the same function, so 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 mark readOnlyHint=true, and the description adds non-obvious behavior: the exactly-one identifier rule, the default diff target, and the full return shape. It does not discuss failure/error behavior, but the read-only annotation lowers 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 dense but well-structured: purpose first, then identifier selection rules, default behavior, and return shape. Every clause carries useful information without padding.

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

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

Since there is no output schema, the description compensates with an explicit return shape covering from/to endpoints and the diff summary. Combined with the rich input schema and read-only annotation, an agent has everything needed 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?

Schema coverage is 100%, so the schema already documents each property. The description still adds value by applying the exactly-one rule across both `from` and `to` (the schema only states it on `from`), and by surfacing the stable-sha256 preference in one place.

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: 'Compute a semantic diff between two model revisions' and enumerates the diff categories (added/removed/modified items plus metadata changes). This clearly distinguishes it from version-listing/restoration siblings even 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?

It gives concrete guidance on identifier selection ('exactly one of', revision_id preferred) and the default behavior when `to` is omitted. It does not explicitly compare against sibling tools such as layerz_history or layerz_restore_version, so it stops short of full alternative routing.

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

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

The description goes well beyond the readOnlyHint annotation by explaining storage is out-of-band, the binary never transits agent context, URLs and files expire after 24h with a daily purge, and branch behavior differs for dashboards vs statements. It also explicitly confirms read-only API key support. This is rich, non-obvious behavioral context that helps the agent set user expectations.

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

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

The description is front-loaded with the core action and result, then progressively adds branch behavior, storage semantics, expiry/refresh, return fields, and read-only availability. Every sentence adds necessary information and nothing is redundant or filler.

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

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

Given there is no output schema, the description explicitly enumerates the return fields. It also covers edge cases such as branches, expiration, refresh behavior, and read-only key support. An agent has enough information to invoke this tool correctly and to set reasonable user expectations.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description adds meaningful semantics beyond the schema for branch_id, explaining that statements and single-value widgets reflect one branch while dashboards keep all branches, and that it defaults to the base branch. This improves correct invocation.

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 ('Generate the model as an Excel (.xlsx) workbook') and names the exact resource and output format. It also distinguishes itself by noting it is 'the same export the web app produces', which clarifies what the artifact contains. This clearly differentiates the tool from the many model-manipulation siblings.

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

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

The description provides clear usage context: call this when an Excel export is needed, pass branch_id when branches exist, and re-call to refresh expired links. It does not name exclusions or alternative export tools, but none of the siblings appear to be a competing export path, so the guidance is adequate.

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 materialized snapshot behavior, projection to this model's grain with nulls outside source coverage, non-automatic refresh, and per-link failure handling that does not touch stored values. These details go well beyond the annotations (readOnlyHint=false, destructiveHint=false) and there is no contradiction between text and 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 dense and well organized: it front-loads the core concept, then explains the two op modes, then points to sibling tools, and ends with the critical read-only-key limitation. Every sentence carries useful information with no filler.

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

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

The description covers creation, retargeting, refresh behavior, permissions, failure semantics, and the resulting referenceability of the line, which is strong for a dual-mode tool. However, there is no output schema and the description does not state what a successful link or refresh returns, leaving a modest gap for an agent expecting a response shape.

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?

Although the schema already documents all 10 parameters with 100% coverage, the description adds meaningful operational semantics: link vs. refresh behavior, uid retargeting, uids as a refresh filter, the name default to the source item, parent container types, source_model_id as the model to read from, and the summary's role in version history. This goes well above the baseline for high schema coverage.

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

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

The description states a specific action ('Link this model to an item of ANOTHER Layerz model') and a concrete resource, with the Excel linked-workbook analogy making the concept immediately understandable. It also names the sibling tools layerz_external_ref_status and layerz_unlink_external_ref, so an agent can distinguish this tool from related ones.

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

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

It explicitly directs the agent to read links with layerz_external_ref_status and detach one with layerz_unlink_external_ref, giving clear routing to alternatives. It also gives crucial when-to-use constraints: refresh is the ONLY way values update, it requires read access to the source model, and it is unavailable for read-only API keys.

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's 'Readable by any member' adds context about permissions and access requirements. It also explains the `stale` flag semantics ('the source model changed since the last sync in a way that moves the values'), which is valuable behavioral context beyond the schema. No contradiction with annotations.

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

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

The description is compact and front-loaded: it states the core function first, then the `stale` flag detail, then access notes, then mutation alternatives. 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?

For a read-only list tool with one parameter and no output schema, the description covers the essential behavior, access, and related mutation tools. It does not describe the exact return format or pagination, but given the simplicity and annotations, this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents the `model_id` parameter. The description does not add further parameter-level detail beyond what the schema provides, but it does clarify that the parameter is the target model and that it may be ignored for model-scoped keys. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists a model's external references with a `stale` flag and source health, using a specific verb ('List') and resource ('a model's external references'). It distinguishes itself from sibling tools by explicitly naming the mutation tools (layerz_external_ref / layerz_unlink_external_ref) and noting it is read-only.

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

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

The description explicitly states when to use this tool: to list external references and check staleness/source health. It also provides exclusions: 'Readable by any member, no source-model access needed' and directs mutation actions to sibling tools. This is clear guidance for an agent to select this tool 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?

With readOnlyHint=true annotation, the description reinforces safety by framing it as a read operation. It adds value by explicitly stating the 3000-char cap, the return shape ({ content }), and the empty-string behavior when unset, which goes beyond the annotation's minimal signal.

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 purpose and follows with important context about preferences and return format. It is slightly verbose but every sentence serves a purpose—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?

Given no parameters, no output schema, and read-only annotations, the description adequately covers the tool's behavior, limitations (cap), and edge case (empty string). It is complete for a simple getter tool; missing only explicit sibling differentiation in usage guidance.

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 0 parameters, so the schema conveys all structural info. The description adds no parameter syntax, which is unnecessary. Baseline 4 is appropriate given the absence of parameters and the schema coverage being trivially complete.

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 reads account-wide custom instructions for AI agents, specifies the scope (user-level, across all models), and distinguishes it from model-level FINANCE.md. This is a specific verb+resource description that sets it apart from the sibling layerz_get_finance_md tool.

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 explains when to treat the instructions as standing preferences and notes they are delivered in MCP server instructions at session startープroviding context for when an agent might still call this tool. It mentions FINANCE.md overrides, which implicitly differentiates from get_finance_md, though it does not explicitly name that sibling.

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 adds meaningful behavioral detail: the exact return shape, the source enum, optional fields, and the null/204 behavior when no FINANCE.md exists. This goes well 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?

The description is front-loaded with the core action and usage directive, then efficiently covers the spec link, return shape, and null case. Every sentence serves a purpose; no filler or redundancy is present.

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

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

For a simple read-only tool with one parameter, the description is complete: it defines what the resource is, when to call it, what it returns, and the missing-document case. The lack of an output schema is compensated by the explicit return field listing.

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

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

Schema coverage is 100% and the model_id parameter is already well documented in the input schema, including UUID format and key-scope behavior. The description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description opens with 'Read the FINANCE.md attached to a model', a specific verb+resource combination, and clarifies the document's role as the financial conventions standard. It is clearly differentiated from siblings like layerz_set_finance_md and layerz_get_custom_instructions.

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

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

The description gives explicit usage context: 'Call this FIRST when starting to work on a model' and states that every other tool result must be interpreted under these conventions. It does not explicitly name alternatives or when-not-to-use conditions, but the priority instruction is strong and clear.

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

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

Annotations provide readOnlyHint=true, so the agent already knows this is a safe read operation. The description adds useful context: it warns about the heavy payload, which is behavioral information beyond annotations. It also implies the response includes items, lists, timelines, and metadata, which adds clarity. There is no contradiction with annotations.

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

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

The description is two sentences, front-loaded with the purpose ('Read full detail of a model') and then adds the heavy payload warning and alternative. Every sentence adds value; no fluff or verbosity. It is appropriately concise and structured for quick parsing.

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 a single parameter with full schema coverage, no output schema (so return format is not documented), and annotations cover safety, the description covers the essential: what it reads, the payload size, and when to use an alternative. It doesn't describe return format or pagination, but for a simple get-by-id tool, this is adequate. A 4 is appropriate for near-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 description coverage is 100%, and the schema already describes model_id with details about UUID format and scoping behavior. The description does not repeat parameter details but adds nothing new either. Since coverage is high, a baseline of 3 is typical, but the description's mention of different payload weights implicitly clarifies the parameter's role (selecting the model to read), so it slightly elevates to 4 for reinforcing usage 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 clearly states 'Read full detail of a model' with a specific verb ('Read') and resource ('model'), and enumerates the content ('items, lists, timelines, and metadata'). It also differentiates from sibling layerz_read by noting this is the heavy payload variant. This distinguishes it from other siblings and provides 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 contrasts with layerz_read, advising 'prefer layerz_read for snapshots'. This gives a specific alternative and a condition (snapshots) for when to use the other tool. However, it doesn't provide detailed 'when-not-to-use' scenarios beyond the heavy payload hint, so it is clear but not exhaustive.

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

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

Beyond the readOnlyHint annotation, the description adds significant behavioral detail: the template id equals a model id, the guide is the live FINANCE.md rather than a snapshot, changes propagate live, and the operation is account-level and read-only. This tells an agent exactly what to expect and how the data relates.

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 not bloated; every sentence contributes a distinct fact. It is front-loaded with the core read operation. It is slightly longer than strictly necessary due to workflow guidance, but that content is useful rather than filler.

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

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

With no output schema, the description carries the burden of explaining what the tool returns: the blueprint plus the markdown guide. It also covers id semantics, edit propagation, and post-fork steps, making the tool fully comprehensible for an agent to invoke and interpret.

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 template_id fully, including its source via layerz_list_templates. The description adds extra meaning by revealing that a template's id equals its model id, which helps an agent reason about id provenance and the relationship to FINANCE.md.

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

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

The description clearly states a specific action and resource: 'Read a template in full: its blueprint plus its description.' It defines what is included, distinguishes the return content from other getter tools, and uses a concrete verb rather than restating the title.

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 reading and applying templates, explains that editing the guide happens through layerz_set_finance_md, and advises updating the new model's FINANCE.md after forking or applying. It lacks an explicit 'when not to use' statement, but the usage context is strong 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 mark the tool as readOnly, and the description adds substantial behavioral detail beyond that: snapshots persist at mutation boundaries, old versions are filtered but stored, hidden_count explains empty results, and pinned versions bypass retention. No contradiction with annotations exists.

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

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

The description is long but dense and front-loaded. Every sentence adds operational meaning, such as revision_id stability, hidden_count semantics, and pinned-version behavior. Given the absence of an output schema, the included return-shape summary is necessary rather than 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?

Since there is no output schema, the description provides the full return shape, retention-window behavior, pin-cap semantics, and ordering ('newest first'). It also clarifies model_id handling for key scopes. The tool is complex, and the description covers the call-relevant details well.

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 limit, since, and model_id. The description mostly restates that since or limit can scope the response, adding little parameter-specific meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: 'List the most-recent change history (versions) for a model.' It also defines what a version is and clarifies the relationship to sibling tools like layerz_diff and layerz_pin_version, making the tool's role easy to distinguish.

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 usage context: the returned revision_id can be used with layerz_diff or to detect concurrent writes, and since/limit can scope the response. It does not explicitly say when to choose this tool instead of layerz_history_for_item or layerz_restore_version, so it lacks full when-not 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 goes beyond the readOnlyHint annotation by explaining the traversal method (oldest→newest, consecutive diffing) and the output structure, which is not present in annotations. It clarifies that only events where the UID changed are reported, adding behavioral depth that aids the agent in understanding what to expect.

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, using three sentences to convey the core action, method, and output format. Key information like the return structure is front-loaded, and the reference to layerz_diff for field semantics avoids redundancy. It's slightly dense but well-organized.

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 tool with no output schema, the description provides a thorough return structure and explains the scanning behavior (limit, retention) implicitly through the schema. It covers the key aspects an agent needs, though it could explicitly mention the limit default and max, but these are already in the schema, so completeness 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?

Since schema description coverage is 100%, the baseline is 3. The description reinforces the `fields` parameter's shape (same as layerz_diff field-level entries) and details the return format, but doesn't add substantial new meaning for uid, limit, or model_id beyond their schema descriptions, which are already explicit.

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 it traces per-item change history for a UID, specifying the operations (added, modified, removed), actor, and field changes. It differentiates itself from sibling layerz_history by focusing on a single item, making its purpose unambiguous and distinct.

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 implicitly conveys usage by emphasizing per-item tracing and returns events for a requested UID, contrasting with layerz_history which likely covers full model history. It doesn't explicitly state 'when not to use' but provides sufficient context for an agent to select this tool for item-level audits.

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

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

Beyond the destructiveHint annotation, the description explicitly warns that replace mode wipes previous input rows, all writes happen in a single persist call, dry_run leaves the model untouched, and grain mismatches can corrupt other periods. It also discloses the read-only API-key restriction and deterministic 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 long but front-loaded with the core behavior: 'Import a stacked branch of values onto the model.' Each section covers a distinct mode or edge case, so most sentences earn their place, but the density of compound sentences requires careful parsing.

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 almost every important behavior, including result counters, dry_run output, grain validation, carry-forward semantics, and read-only-key restrictions. It is not fully complete because merge, record_import, and replace_scope are not described anywhere, and there is no output schema to fill that gap.

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

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

With only 38% schema description coverage, the description does substantial compensative work: it explains entries vs file_id, branch.id, actuals_through, display_name, replace, replace_source_id, dry_run, sheet_name, and structure_override. However, merge, record_import, and replace_scope remain undocumented in both the schema and the description.

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: 'Import a stacked branch of values onto the model.' It then distinguishes the fresh-branch and replace modes and separates the file_id and entries paths, making it clear this is the branch-data import tool rather than layerz_create_model or layerz_import_mapping_template.

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 guidance: prefer file_id for spreadsheets, build entries by hand only for computed values, use replace:true with branch.id to refresh an existing branch, pass replace_source_id for re-imports, and use dry_run to preview. It lacks an explicit contrast with layerz_update_branch, but the mode-specific directions largely cover the decision space.

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 well beyond annotations, disclosing conflict resolution ('imported rule wins on a pattern conflict'), target translation by display name, the 'one model = one set' model, the need to re-sync to classify, and the read-only API key restriction. It does not contradict the annotations (readOnlyHint false, destructiveHint false).

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

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

The description is dense but each sentence serves a purpose: core action, conflict behavior, template_id sourcing, re-sync instruction, and API key restriction. It is front-loaded with the main action and avoids fluff, though slightly longer than necessary.

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

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

Despite having no output schema, the description covers the mutation's effects, conflict resolution, follow-up re-sync, and access restrictions. It also references the source of template_id. The summary and model_id parameters are already well documented in the schema, so the description 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 coverage is 100%, so the baseline is 3. The description adds meaning to template_id by specifying it comes from layerz_list_mappings and can be a system_template or user_template, and also mentions 'or one of your catalogs'. It reinforces the 'one model = one set' constraint, providing extra context 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 states a specific verb and resource ('Import a mapping template ... by DUPLICATING its rules into the model's single mapping set'), and explicitly clarifies that this is how a template 'applies' with no implicit cross-model application. This distinguishes it from sibling tools like layerz_promote_template and layerz_set_mapping.

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 explains when to use it (to apply a template/catalog to a model), gives the source for template_id (layerz_list_mappings templates), and notes it is unavailable for read-only API keys. It does not explicitly name alternative tools to use instead, but the context strongly implies it is the only way to apply a template.

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 safety profile is covered. The description adds meaningful behavioral context beyond the schema: the default Layer is always present, and it explains the semantics of actuals_through_locked (pinned by user, source syncs will not move it). This helps the agent interpret results correctly.

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 plus a parenthetical field list. The field list is front-loaded, and the behavioral note about actuals_through_locked is valuable. Slight redundancy with the title ('List branches' vs 'List the Layer definitions') but 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 read-only list tool with one optional parameter and no output schema, the description covers the key semantics: what is returned, the guaranteed presence of the default Layer, and the meaning of a non-obvious field. It doesn't describe pagination or sorting, but those are minor for a list tool with annotations already covering safety.

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 model_id thoroughly, including its optionality and behavior for different key scopes. The description adds no parameter-specific meaning beyond the schema, so 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 ('List') and resource ('Layer definitions on a model'), and enumerates the returned fields. It distinguishes itself from sibling tools like layerz_list_models and layerz_list_transactions by specifying it lists Layers on a model, though it doesn't explicitly name a sibling alternative.

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 usage context: it lists Layers on a model, and the model_id parameter description clarifies when it is required vs ignored. However, it doesn't explicitly state when to use this tool over alternatives like layerz_list_models or layerz_get_model, nor does it provide exclusions or conditions.

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

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

Annotations already mark readOnlyHint=true, but the description goes beyond by detailing that it 'Never returns stored credentials', explains the `legacy_import_id` special row semantics, and notes the sync/update/rebind capabilities of file sources. It also clarifies the distinction between materialized pre-staging imports and newly staged ones, giving the agent deep behavioral context.

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

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

The description is detailed and slightly long, but every sentence adds value. It front-loads the core purpose and then layers in distinctions and related-tool routing. One redundant phrase: 'a staged upload from the web wizard or layerz_import_branch { file_id }' – the reference to `layerz_import_branch` is useful, but the parenthetical could be trimmed. Overall, it is well-structured and information-dense.

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 moderate complexity (one optional parameter), the description covers purpose, usage, related tools, security implications, and edge cases (legacy imports). There is no output schema to explain, but the return row content is described in detail. An agent would know exactly when and how to call it, and what to expect back.

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 parameter is fully documented. The description adds contextual value by explaining that model_id is required for user-scoped keys but ignored for model-scoped keys, which is useful beyond the schema's formulation. However, this is incremental rather than essential, and the baseline is already high.

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 'List every data source feeding a model' and enumerates the types (API connectors and file imports), distinguishing it from siblings like layerz_list_branches or layerz_list_transactions. It is a specific verb+resource definition that leaves no ambiguity about what is returned.

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 contrasts with related tools: 'layerz_list_transactions' for browsing staged rows, 'layerz_manage_integration' for mutating, and 'layerz_delete_integration' for disconnecting. It also explains the difference between legacy imports and new staging imports, and explicitly says 'Connect a new API key from the web app' – a clear when-not-to-use signal. This is excellent 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?

Beyond the readOnlyHint annotation, the description discloses meaningful runtime behavior: case-insensitive GLOB semantics, default results matching what the importer actually applies, the heavier cost of coverage computation, and the legacy PCG overlay caveat. This gives the agent a much richer understanding of edge cases and side effects than annotations alone.

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 carries operational meaning, and the core purpose is front-loaded. The length is justified by the tool's nuanced scope model and optional flags, with no filler or repetition.

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

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

With no output schema present, the description compensates by explaining the returned concepts: sets/mappings with scopes, templates, match_count, and coverage block. For a nuanced read-only tool with three optional parameters, it supplies everything 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?

Although the schema already describes all three parameters, the description adds significant meaning: it explains GLOB matching patterns, clarifies that include_user_mappings surfaces account-wide catalogs, and defines what the coverage block contains. This materially improves parameter understanding beyond the structured 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 first sentence names a specific verb and resource ('List the import classification rules in scope for a model') and clearly differentiates the three mapping-set scopes. This distinguishes it from sibling mapping mutation/import tools like layerz_set_mapping and layerz_import_mapping_template.

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 explains when to use the tool and when not to: a model classifies only with its own model rules, and catalogs/templates apply by being imported via layerz_import_mapping_template, never implicitly. It also gives precise conditions for enabling include_user_mappings and include_coverage, so an agent knows exactly when to request the optional behavior.

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=false, so the safety profile is covered. The description adds genuine behavioral value by disclosing that results include can_write and that model-scoped API keys return only the bound model. This goes beyond the structured annotations without contradicting them.

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 focused sentences, each earning its place: the core action, the can_write field semantics, and the scoped-key special case. The most important information 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?

This is a simple, read-only, zero-required-parameter list tool. The description covers the operation, access scope, result flag, and scoped-key behavior. No output schema exists, but the description says enough about the result shape for an agent to call it confidently; pagination or full field enumeration would be nice but are not essential.

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 fully documents q and writable, including wildcard behavior and omission semantics. The description does not need to repeat parameter details, so the baseline 3 applies.

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

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

States a specific verb and resource: 'List models the authenticated user can access.' It clearly distinguishes itself from get_model and other layerz_list_* siblings by focusing on the models the caller can access. The title and description align, and the description adds useful 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 provides clear context: this is the tool for listing accessible models, with optional can_write information. It does not explicitly compare itself to get_model or list_templates, so alternatives are not named, but the list-vs-get distinction is strongly implied and the context is clear.

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

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

Annotations already declare readOnlyHint=true, but the description adds substantial behavioral context: it explains the security implication of 'public' link_visibility (anyone with the link can read, even if the roster lists only the owner), notes that the model URL is the same for access and sharing, and clarifies that changing visibility is owner-only via the web app. This goes well beyond the annotation and gives the agent accurate expectations.

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

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

The description is compact and front-loaded with the core purpose, then adds necessary context about link_visibility and permissions. Every sentence contributes value, and there is no redundancy or filler. The structure flows from what it does, to the return details, to usage notes.

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

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

There is no output schema, so the description must explain the return value, and it does thoroughly: the roster contents (owner, collaborators, pending invites with role and id) and the link_visibility field with its two possible values and their implications. It also notes the URL equivalence and availability to read-only keys. For a single-parameter read tool, nothing essential is missing.

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

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

The input schema already describes model_id with 100% coverage, including when it is required vs. ignored. The tool description does not add any additional parameter-level semantics beyond what the schema provides. Since the schema carries the full burden, the baseline of 3 is appropriate; the description adds no meaningful extra information about the parameter itself.

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

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

The description opens with 'Read a model's sharing roster' – a specific verb and resource – and then details exactly what is returned (owner, collaborators, pending invites with role and id, plus link_visibility). It clearly distinguishes this from the mutation siblings like share_model and revoke_share by framing it as a read operation. The scope is unambiguous.

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

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

The description states that the tool is read-only and available to any member including read-only API keys, and explicitly notes that changing link visibility is not possible via this API (done in the web app). However, it does not explicitly name alternative tools for granting/revoking access (e.g., layerz_share_model, layerz_revoke_share) or state conditions when to use those instead. The read-only context is clear, but sibling routing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's 'Account-level, read-only' adds a small amount of context. The description also discloses what each entry contains (name, subtitle, glyph, description, category, scope, structure summary), which helps the agent understand the return shape without an output schema. It doesn't mention pagination or ordering, but for a list tool with one optional filter, 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 a single dense paragraph that front-loads the core purpose and return contents, then adds the two consumption paths. It earns its length by explaining the entry fields and the follow-up tools, though it could be slightly tighter by trimming the parenthetical examples.

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

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

For a read-only list tool with one optional parameter and no output schema, the description covers the return entry fields, the account-level scope, and the two follow-up actions. It doesn't describe pagination or sorting, but those are minor gaps for this tool's simplicity.

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

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

Schema description coverage is 100%, so the schema already documents the single 'scope' parameter. The description adds the meaning of the filter values ('system' curated, 'user' your own), which is helpful but not essential. 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 ('List') and resource ('reusable model templates'), and distinguishes itself from siblings by clarifying it returns curated system templates plus the user's own. It also names the two sibling tools that consume the results (layerz_create_model, layerz_build_from_blueprint), which makes its role in the workflow clear.

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

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

The description explicitly says when to use this tool (to pick the right base from a prompt) and names the alternatives for the next step (fork vs. apply as a module). It also notes the optional scope filter for system vs. user templates. This is strong routing guidance.

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

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

Annotations already provide readOnlyHint: true, and the description reinforces this with 'Read-only — it never writes.' Beyond that, it discloses detailed routing behavior: rows without a matching rule are skipped unless auto-create is opted in, __ignore__ rules yield 'ignored' status, and CSV mode returns a signed download_url. This adds substantial behavioral context not covered by annotations or schema.

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

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

The description is dense but every sentence earns its place: purpose, routing semantics, read-only note, use case, filters, and CSV behavior. It is front-loaded with the core purpose. It could be slightly trimmed, but the structure is logical and the information density is high without being verbose.

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 no output schema, the description thoroughly explains what the agent will receive: inline annotated rows or a download_url for CSV, with notes on routing, skip logic, and ignore rules. It covers filters, required connection_id, and model_id scope. There is no critical missing information an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds value by explaining the interaction of filters with CSV mode (filters don't apply) and the meaning of the routing annotations, which are not in the schema. It also clarifies that connection_id comes from layerz_list_integrations, which is extra context beyond the schema's generic description.

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

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

The description opens with a specific verb and resource: 'Read a data source's staged transactions', and immediately scopes it to API/csv imports via layerz_list_integrations. It distinguishes itself from sibling list tools (e.g., list_mappings, list_models) by the routing annotations and CSV export behavior, so an agent can tell it apart without opening the schema.

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

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

It explicitly states when to use the tool: 'Use it to find rows that route nowhere before writing a mapping rule.' It also explains the CSV format alternative and that filters don't apply there. It does not explicitly state when not to use it or name alternatives, but the primary use case is clear and actionable.

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

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

The description goes well beyond the annotations by detailing side effects: sync is an idempotent replace of the source's own rows, rebind wipes rows from detached branches, update can re-fetch and re-stage, and `deletable_items` are proposed but never auto-deleted. It also states that credentials are never sent over MCP and that read-only keys are unsupported. These details give the agent a precise mental model of what the tool changes and what it preserves, with no contradiction against `readOnlyHint: false` or `destructiveHint: false`.

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

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

The description is long and dense, but nearly every clause earns its place by covering an operation, a side effect, or an exclusion. It is front-loaded with the central `by op` concept and then expands each operation in a logical sequence. Minor readability cost comes from long parenthetical chains and run-on sentences, which prevents a perfect score.

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 three-operation tool with nested config, nine parameters, and no output schema, the description is remarkably complete. It tells the agent what each operation returns (`unmapped`, `proposed_window`, `deletable_items`, `cutover_changes`, `warnings`), references the sibling tool needed to pin a cutover, and clarifies both setup prerequisites and operational constraints. Nothing essential is missing for correct invocation.

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

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

The input schema already provides 100% parameter coverage with detailed descriptions, so the baseline is strong. The tool description adds meaningful semantic context on top by tying parameters to operations (`branch_ids` to `rebind`, `target_branch_id` to `sync` for unbound connections, `config` to `update`) and by explaining consequential behavior like 're-fetches + re-stages' versus 're-project'. It does not need to repeat the schema's config-level 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 opens with a specific verb-plus-resource statement ('Sync or reconfigure a data source') and then enumerates the three distinct operations (`sync`, `rebind`, `update`) with concrete meanings. It also differentiates itself from sibling tools by explicitly pointing to `layerz_delete_integration` for disconnecting a source, so an agent can distinguish when this tool is appropriate.

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 explains when each `op` should be used, including edge cases: `dry_run` for previews, `target_branch_id` for unbound connections, `rebind` for re-pointing to branches, and `update` for renaming or changing config. It explicitly names exclusions: new credentials should be set up in the web app, and the tool is unavailable to read-only API keys, which is strong 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?

Adds significant behavioral detail beyond annotations: deterministic operation ('No LLM call'), return shape (top 3 candidates, four methods, score), and meaning of empty results. Annotations already indicate readOnlyHint, and the description enriches this without contradiction.

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

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

Three concise sentences, each with purpose: purpose, output details, and action on empty results. No filler, front-loaded with the core function.

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

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

For a read-only matching tool with no output schema, the description explains the output sufficiently (candidates, methods, score, empty meaning). It lacks explicit mention of how to interpret scores or handle multiple candidates, but that is a minor gap given the simplicity.

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 both parameters, so the baseline is 3. The description repeats the purpose but adds no parameter-specific semantics beyond what the schema already provides (e.g., no additional format, constraints, or interaction 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?

Description states a specific verb ('Resolve') and resource ('free-text labels to existing item UIDs on a model'), and details the matching methods. This clearly distinguishes it from all siblings; no other tool matches labels to item UIDs.

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

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

Provides clear context for use (import workflow) and a decision rule ('Empty candidates means the agent should create the item before importing'). However, it does not explicitly name alternatives or state when not to use it, leaving some inference to the agent.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds substantial behavioral detail beyond annotations: the result is 'token-optimized, never includes the raw binary,' the exact output components are listed, and re-calling with structure_override is described as the correction path for misdetected ledgers.

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 carry a large amount of information with no filler: the first defines the operation and output, the second connects it to its downstream siblings, and the third explains the correction workflow. It is appropriately concise and front-loaded.

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

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

Given the tool's moderate complexity, the description covers the essential operational context: what it parses, what it returns, how it fits into the broader workflow, and how to recover from misdetection. There is no output schema, so the description's explicit listing of return contents is sufficient. The schema covers sheet_name behavior, completing the picture.

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 fully documents all parameters and nested fields. The description adds pipeline-level context around structure_override (e.g., misdetected 'Débit' column), which is helpful but does not add parameter-level semantics beyond what the schema descriptions already provide.

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

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

The description clearly states a specific verb and resource: 'Parse an Excel/CSV file uploaded out-of-band via layerz_create_upload_url.' It lists the exact return payload (timeline, suggested_structure, row labels, column headers with samples) and distinguishes this parse step from the sibling pipeline tools like layerz_match_items and layerz_import_branch.

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 pipeline context: the agent typically feeds row labels into layerz_match_items and then builds entries[] for layerz_import_branch. It also gives explicit re-call guidance when misdetection occurs, but it does not explicitly state when not to use this tool relative to all 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?

The description discloses far more than the annotations convey: batch atomicity ("if one op fails validation ... nothing is persisted"), implicit auto-posing of bare-reference formulas as callup mirrors, rejection codes (FORMULA_EXPR_AND_CHILDREN, SCALAR_FUNCTION_MISUSE), idempotency of list_create by name, and warnings like BARE_SELF_LAG_IN_LIST_FORMULA. It also states "Not available for read-only API keys" and details list-mode value regimes that silently drop scalar values. Annotations (readOnlyHint=false, destructiveHint=true) align with "Mutate a model" — no contradiction.

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

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

The description is an enormous, roughly 2,000-word wall of text with no headings, bullets, or section breaks. It duplicates schema content nearly verbatim (the role enum guidance appears in both the description and the schema's role fields) and buries important distinctions (op types, formula grammar, list mechanics, meta, chart rendering) in a single continuous stream. While technically dense, it is not appropriately sized or scannable for an agent that must quickly select and invoke 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?

For a tool of this complexity — 12 op types, a full formula language, list-mode rules, callup semantics, and meta fields — the description covers essentially all input and behavioral context, including compute/dry_run/compute_branch usage and cross-tool references. The only notable gap is the success return payload: there is no output schema, and while "Pass compute with UIDs to get calculated values back" hints at output, the standard response (e.g., real UIDs for temp ids, health results) is never documented.

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 meaningful semantics absent from the schema: ops must be JSON objects with a string `op` field and never JSON-encoded strings; temp ids resolve inside formulas; scalar value/values are rejected on list-mode items and silently dropped; period-keyed maps merge into the existing series rather than replacing it; list_create is idempotent by name. These are exactly the details that prevent an agent from constructing invalid invocations.

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

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

The first sentence states a specific verb and resource: "Mutate a model with batched ops" followed by the full op list (create/replace/update/delete/move/list_create/list_update/list_delete/meta). This unambiguously identifies the tool as the model-mutation companion to sibling tools like layerz_read and layerz_import_branch, with no ambiguity.

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

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

The description gives concrete routing guidance: dataset entities and imported actuals belong to layerz_import_branch ("imported actuals/overrides are import-owned (use layerz_import_branch or the Sources import)"), mappings and health should be inspected via layerz_read, and read-only API keys cannot use this tool. It also advises preferring replace over create+rewire+delete and nested sections over formula aggregators for structural grouping. The guidance is rich but scattered throughout rather than stated in a dedicated when-to-use section.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context: pinning past the cap fails with a 403 naming the limit, pinning an already-pinned version is a no-op, unpinning frees a slot, and the tool is mutating and unavailable for read-only keys. No contradiction with annotations.

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

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

The description is dense but well-organized: purpose first, then identifier selection, then cap behavior, then return value, then access requirements. Every sentence adds information. Slightly long, but each clause earns its place given 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?

The description covers purpose, identifier selection, cap behavior, error semantics, return value, and access requirements. There is no output schema, so the explicit return shape { ok, version_id, ... } is valuable. For a mutating tool with nested parameters, this is complete.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the preferred identifier (revision_id, stable sha256), the 'exactly one of' constraint, and the meaning of pinned: false. It doesn't add syntax details beyond the schema, but the schema is already rich.

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 ('Pin') and resource ('a version'), and explains the purpose: keeping it listed, diffable, and restorable beyond the plan history window. It also covers the unpin case, which distinguishes it from sibling tools like layerz_restore_version and layerz_history.

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 when to use this tool (pin a version for retention beyond the history window) and gives concrete exclusions: not available for read-only API keys, requires write access, target must be inside the plan history window or already pinned. It also names the cap behavior and the alternative action (unpin another version first).

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 rich behavioral context beyond the annotations: it flips the model in place without copying, keeps content editable, derives the blueprint on demand, links the usage guide to FINANCE.md, and explains scope-based visibility and admin gating. No contradiction with idempotentHint or destructiveHint.

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 dense sentences with no filler. The core behavior is front-loaded, and each subsequent clause adds essential operational detail (scope, admin restriction, key restrictions, edit path).

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

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

Despite having no output schema, the description is complete for correct invocation: it covers the operation, side effects, ownership precondition, scope semantics, admin-only behavior, API-key restrictions, and how the usage guide is managed. The required parameters are already fully documented in 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: scope defaults and permissions, model-ownership requirements, API key restrictions, and the FINANCE.md relationship. It does not add much beyond the schema for name or summary, but the added context is material.

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: 'Promote a model you own into a reusable template.' It clearly distinguishes this from sibling tools by noting the in-place flip (no copy) and the concrete outcome of appearing in layerz_list_templates.

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

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

It gives clear when-to-use context: promote a model you own, with scope defaults and admin-only restrictions for system scope. It also states availability constraints ('Not available for read-only or model-scoped API keys'), though it does not explicitly name alternative tools for comparison.

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=false, so the safety profile is known. The description adds significant behavioral context: the `computable: false` response leading indicator, the meaning of a broken DAG (CIRCULAR_DEPENDENCY), and the degenerate zero-fill behavior. It also explains the effect of with_values and branch_id on computation. This goes well 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 compact and front-loaded with the core purpose. The second sentence about `computable: false` is valuable but slightly dense; it could be split for readability. Overall, every sentence earns its place, and the structure is efficient.

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

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

Given the tool's complexity (12 params, no output schema), the description covers the key behavioral edge case (broken DAG) and the main computation flags. It doesn't explain return value structure in detail, but with no output schema, the description could do more to describe what the response looks like. However, the description's focus on the critical failure mode and parameter interactions makes it largely complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters. The description adds some context (e.g., 'with_values=true to compute', 'branch_id lets you audit base-vs-overlay'), but most parameter semantics are already in the schema. Baseline 3 is appropriate because the description doesn't need to compensate for missing schema 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?

The description states a specific verb ('Read') and resource ('model snapshot'), and clarifies it returns items plus optional computed values. It distinguishes itself from siblings by mentioning filtering by UIDs or roles and the optional with_values computation, which is unique among the listed tools.

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

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

The description gives clear context on when to use this tool: to read a model snapshot, filter by UIDs/roles, and compute values. It doesn't explicitly name alternatives or exclusions, but the sibling list shows many other tools (e.g., layerz_get_model, layerz_dependencies) and the description's focus on snapshot reading with optional computed values implies when it's appropriate. It lacks explicit 'use X instead' guidance, so not a 5.

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

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

Goes beyond annotations (readOnlyHint=false, destructiveHint=true) by clarifying the non-destructive nature: 'the current live state is first saved as a new restore version' and 'a restore can itself be undone by restoring that backup.' Also explains backup_version_id null behavior and that the restored state is recorded as a history entry. This is rich, context-adding transparency.

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 opens with the core action, moves to target selection, then safety/undo behavior, then the backup edge case, then guidance to consult history, and closes with return shape and auth. No repetition or filler.

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

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

For a mutating tool with nested parameters, no output schema, and several edge cases, the description covers all necessary context: how to choose the target, what the backup/undo behavior is, the return fields, and the access/retention requirements. 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?

Schema description coverage is 100%, so parameters are already well-documented. The description adds value by explaining the preferred choice among the three version identifiers (revision_id preferred, stable across renames) and by elaborating the backup semantics and return object, which enriches 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 states a specific verb and resource: 'Restore the model to a previous version' and details the effect ('replacing the current items, schema, and inputs with that snapshot'). It clearly distinguishes from sibling tools by focusing on restoring a version rather than listing (layerz_history), diffing (layerz_diff), or other operations.

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

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

Provides explicit guidance on target selection ('exactly one of revision_id, version_number, or id'), names the preferred option, and instructs to 'Pick the target by reading layerz_history / layerz_diff first.' It also states prerequisites: write access, retention window, and read-only key restrictions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the destructive nature is covered. The description adds behavioral context beyond annotations: ownership requirement and read-only API key ineligibility. It does not detail reversibility or downstream effects, but destructiveHint covers the core risk for this simple revoke action.

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, well-structured sentence that front-loads the action and includes essential usage constraints without filler. Every clause contributes operational value.

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

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

For a two-parameter tool with one required field and full schema coverage, the description provides all necessary operational context: what is removed, how to identify the target, and permission restrictions. No output schema is present, so the description need not explain return values, and annotations cover safety semantics.

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 parameters are already documented. The description adds meaningful semantics for principal_id by explaining it is the id returned by layerz_list_shares and clarifying the difference between an active-share user id and a pending-invite id, which is beyond the schema's generic description.

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

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

The description uses a specific verb and resource: 'Remove a collaborator or pending invite from a model by principal_id'. It clearly distinguishes this from sibling tools like layerz_share_model and layerz_list_shares by stating exactly what action is performed and what identifier is used.

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 when-to-use guidance by naming the source of principal_id (layerz_list_shares) and distinguishes active shares from pending invites. It also provides clear when-not-to-use constraints: owner-only and not available for read-only API keys.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds that it's an upsert (so it overwrites/creates), that empty string clears instructions, and that it's account-wide applying to all models. It also discloses the read-only key restriction. This adds meaningful behavioral context beyond the annotations, though it doesn't detail side effects like whether existing instructions are replaced atomically.

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 with a distinct purpose: what it does, scope, and routing guidance. No fluff. The key facts (upsert, max length, account-level) are front-loaded.

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

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

For a single-parameter tool with full schema coverage and annotations covering idempotency and safety, the description is nearly complete. It covers scope, alternatives, and auth restriction. The only minor gap is not describing the return value/confirmation, but there's no output schema and the operation is simple enough that this is a small omission.

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

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

Schema description coverage is 100%, so the schema already documents the 'content' parameter fully, including maxLength and the fact that empty string clears. The description repeats the max 3000 chars and Markdown/text but doesn't add much beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the verb 'Upsert' and the resource 'account-wide custom instructions for the authenticated user', with a max length constraint. It distinguishes itself from sibling tools like layerz_set_finance_md by explicitly saying to prefer editing FINANCE.md for model-specific conventions. This is a specific, unambiguous purpose.

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 when to use this tool vs alternatives: 'Prefer editing FINANCE.md for model-specific conventions; use this for cross-model preferences.' It also notes it's not available for read-only API keys, which is a clear usage constraint. This is excellent 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?

Beyond the annotations, it discloses real behavioral traits: schema warnings do not block persistence, the tool is unavailable for read-only API keys, and for templates this FINANCE.md serves as the live usage guide. These are not derivable from the annotations or schema alone.

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?

Every sentence carries a distinct fact: what is upserted, the session-start workflow, source semantics, template side effects, validation leniency, and auth restrictions. It is front-loaded and dense without padding.

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

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

Given that the schema covers all parameters and the annotations cover safety/idempotence, the description supplies the remaining operational context: when to invoke it, side effects for templates, how validation behaves, and auth availability. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already describes each parameter. The description adds value by clarifying source provenance, noting that 'auto' is reserved for generator output, and explicitly requiring the content to parse as YAML front matter.

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: 'Upsert the FINANCE.md for a model.' It also clarifies that the tool accepts the full Markdown document with YAML front matter, which separates it from sibling tools like layerz_get_finance_md, layerz_set_custom_instructions, and layerz_patch.

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

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

It gives an explicit typical workflow: an agent reads FINANCE.md at the project root and pushes it at session start so later layerz_patch and layerz_build_from_blueprint calls share conventions. It also explains when to use source='imported' vs 'user'. It does not explicitly name when-not-to-use alternatives, so it stops short of a 5.

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

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

Annotations already provide idempotentHint: true and readOnlyHint: false. The description adds meaningful behavioral detail beyond this: upsert-by-pattern semantics, the mapping set being created on first use, case-insensitive glob matching, the special __ignore__ behavior that stops rows from counting as unmapped, and the need to re-sync to apply changes. No contradiction with annotations exists.

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

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

The description is dense but well ordered: purpose first, then parameter semantics, then application/when-to-use guidance, then the read-only restriction. The parenthetical examples are helpful rather than filler. It is on the longer side, but each clause earns its place for a tool with nuanced behavior.

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 mutating mapping tool with no output schema, the description covers the essential invocation context: what the tool does, how pattern and target behave, special values, the one-set model constraint, the need to apply via re-sync, and the read-only key limitation. It does not describe the return value or behavior when a rule pattern already matches multiple rules, but those are not blocking for selection and 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 coverage is 100%, so the baseline is 3. The description adds value by explaining pattern matching in detail (case-insensitive, prefix/contains/suffix/exact examples, tested against the keyed source field), elaborating on target's special __ignore__ value, and clarifying that sign adjusts the amount. This goes beyond the schema's shorter parameter descriptions.

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

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

The description opens with a specific verb-resource pair: "Create or update an import classification rule (upsert by pattern)" in the model's single mapping set. It also clarifies the one-model-one-set constraint and implicitly distinguishes itself from the sibling import template by saying "To reuse a catalog's rules instead, import it first."

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 clearly explains when to use this tool for individual classification rules and points to layerz_import_mapping_template as the alternative for reusing a catalog's rules. It also states the follow-up requirement to re-sync or use layerz_manage_integration with op: "update", and notes that read-only API keys cannot use it. It does not exhaustively enumerate when not to use it, but the guidance is 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?

The description discloses substantial behavioral details beyond the annotations: registered users get an active share, unregistered ones a pending invite, and both receive an email. It also specifies ownership and API key restrictions. The annotations only indicate non-read-only and non-destructive, so this description meaningfully enriches the agent's understanding of 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 three focused sentences: the first delivers the core action and state outcomes, the second states prerequisites, and the third points to a sibling. No filler, and the most important information is front-loaded.

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

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

For a mutating action with no output schema, the description covers purpose, side effects, and authorization constraints. It does not explicitly address the conditional nature of model_id (required for user-scoped keys, ignored for model-scoped ones), but this is fully documented in the schema, so the agent can retrieve it when needed.

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 each parameter described in the input schema. The description mentions roles ('viewer or editor') aligning with the role enum but adds no parameter-specific detail that the schema doesn't already provide. Thus, it does not elevate above the schema-driven baseline.

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 'Invite an email to a model as a viewer or editor', a specific verb and resource with role options. It further distinguishes from sibling tools by pointing to layerz_list_shares for reading the roster, making the tool's purpose immediately identifiable.

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 clearly states constraints: 'Owner-only' and 'not available for read-only API keys', which tells the agent when the tool is applicable. It also directs users to layerz_list_shares as the complementary tool for viewing existing shares, though it does not explicitly mention layerz_revoke_share as the alternative for removing access.

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

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

Annotations already mark this as destructive; the description goes further by explaining the exact scope of destruction: the association is severed, but snapshot values persist and the line becomes an ordinary assumption. It also discloses the read-only API key restriction, which is not visible in annotations.

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

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

Two concise sentences, with the core action front-loaded and behavior/auth limitations placed after. Every sentence adds value without redundant restatement of the title or schema.

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

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

Between the schema and description, the agent knows what the operation does, which fields are required, and the auth constraint. The lack of an output schema is not a major gap because the resulting state is clearly described, though there is no explicit success/failure or reversibility detail.

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

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

Schema description coverage is 100%, and the schema already documents `uid`, `summary`, and `model_id` in detail. The description's mention of `uid` merely echoes the schema and adds no new parameter semantics.

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

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

The description states a specific verb ('Detach'), a resource ('external reference'), and the selection key (`uid`). It also clarifies the outcome in a way that distinguishes unlink from delete or re-link 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 implicitly tells an agent when this tool applies: when an external reference should stop following its source. However, it never names alternatives (e.g., layerz_external_ref for re-linking) or explicit when-not conditions. The only stated restriction is read-only API keys, which is an auth boundary rather than a usage-routing rule.

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, the description discloses critical side effects: setting actuals_through pins the cutover and sets actuals_through_locked: true, while null resets to auto and clears the pin. It also adds the auth restriction ('Not available for read-only API keys'). This is rich behavioral context that annotations alone do not provide, and it does not contradict the idempotentHint or destructiveHint 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 well-structured: it front-loads the core action and fields, then explains the nuanced actuals_through behavior, then the auth limitation. Every sentence contributes useful information, though the pinning explanation is slightly long and could be tightened.

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 patch operation with a nested object and no output schema, the description covers purpose, editable fields, default-Layer constraints, side effects, and auth. Gaps include no mention of dataset_id semantics, model_id handling beyond the schema, or return value, but the schema already documents model_id and summary well, so the description is mostly complete for an agent 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 only 50% schema description coverage, the description compensates by enumerating all patch fields and explaining actuals_through semantics in detail, including the pin/reset behavior and the default-Layer restriction. However, it does not explain dataset_id, priority, source_hint, or file_name beyond their names, so the compensation is strong but incomplete.

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: 'Patch an existing Layer' followed by the exact editable fields. It is clear about what the tool does, but it does not differentiate itself from the sibling layerz_patch, and the title says 'Update branch' while the body refers to a 'Layer,' which creates mild ambiguity.

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 useful usage constraints: the default Layer only accepts a subset of fields, and read-only API keys cannot use this tool. However, it never states when to use this tool instead of a sibling like layerz_patch or layerz_import_branch, so the usage guidance is implied rather than 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?

Beyond the readOnlyHint annotation, it discloses that the write path auto-repairs some issues (dangling source_uid/inputs), that certain invariants are only enforced at write (parent_uid), and that the report contains per-issue codes, messages, and item_uids. This is substantial behavioral context and contradicts nothing in 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?

Although long, every sentence earns its place: purpose, then critical limitations, then output format, then usage recommendation. The most decision-relevant fact (read-only sanity check) is front-loaded, and the structure makes it easy to scan.

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

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

No output schema exists, but the description explicitly defines the return structure ({ ok, error_count, warning_count, errors[], warnings[] }) and the error sub-fields. It also covers when to use, what it does, and its limitations—nothing an agent needs to call it correctly is missing.

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

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

The schema already provides 100% coverage of model_id, including format, requiredness per key type, and scope behavior. The description adds no parameter-specific meaning, so the baseline of 3 applies.

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

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

The description opens with a precise verb-resource pair ('Audit a model without writing') and enumerates the exact checks (structural / formula / timeline). It explicitly contrasts with the write path, so an agent can distinguish this from layerz_patch or layerz_create_model without opening their schemas.

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

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

It gives an explicit recommendation ('use it as an agent-side sanity check before sharing') and clearly states what it is NOT (a byte-for-byte write preview) and why ok:true is insufficient to guarantee a write. This frames both when to call and when to avoid relying on it.

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