Foliade

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds useful context by stating that no secrets or payment data are returned, which clarifies the read behavior and privacy boundary. However, it does not describe output structure or other behavioral details, so it only moderately adds 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 a single, front-loaded sentence with no wasted words. Every element—address, plan, and the exclusion of sensitive payment data—contributes to understanding the tool's purpose.

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

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

For a zero-parameter read-only tool with annotations covering safety, the description is reasonably complete. It explains what the tool confirms and what it does not expose. The only minor gap is the ambiguity between 'destination account' and 'connected account,' which could be clearer for agent routing.

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

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

The tool has zero parameters and the input schema is empty, so there are no parameter semantics to explain. The baseline of 4 applies because the description avoids inventing unnecessary parameter-related information and focuses on what the tool returns.

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

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

The description states a clear purpose: confirming the address and plan of the destination account. The verb 'confirms' is specific and the resource scope (account details) is identifiable. While 'destination account' is slightly ambiguous compared to the title's 'connected account,' it is still distinct enough from the many sibling tools.

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

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

The description implies usage for verifying account-level information like address and plan, but it does not explicitly state when to use this tool versus alternatives or when not to use it. Since there are no obvious sibling account-checking tools, the implied context is sufficient but not clearly articulated.

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, and the description does not contradict them. It adds useful scope (theme 'of this account') and impact (styling and media), but it does not state that applying the theme may replace existing catalogue styling or explain how expected_revision guards against that.

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

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

A single front-loaded sentence with no filler. Every word contributes to identifying the operation and its scope.

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 destructive write with no output schema, no parameter descriptions, and no explanation of expected_revision. For an agent to invoke this safely, the description should at least indicate what value expected_revision takes and how to obtain it, so the current description leaves a meaningful 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 0%, so the description must compensate. It refers to 'theme' and 'catalogue' in prose, but it never explains expected_revision—a required 64-hex field—or how it relates to the catalogue's current state.

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: 'Copies the styling and media of a theme of this account onto this catalogue.' This clearly identifies the operation and distinguishes it from theme creation/update tools like foliade_create_theme and foliade_update_theme.

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

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

The description implies the correct use case—applying an existing account theme to a catalogue—but it gives no explicit when/when-not guidance and does not name alternatives among the sibling tools. It is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds genuinely useful behavioral context: 'omitted fields are kept, null is refused', immediate visibility of setting changes on a published catalogue, and the list of what stays outside MCP scope (binary media, PDF replacements, API keys, REST webhooks, team, billing). These go 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 short and front-loaded: the first line gives the core purpose and the key configuring rule, followed by two compact scoping notes. No filler words; each clause earns its place, though the structure is slightly fragmented with the indented 'Setting changes...' and 'Binary media...' lines.

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

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

For a zero-parameter read-only discovery tool, the description is largely complete: it states what will be revealed, when to use it, and what is excluded from MCP control. It doesn't describe the return format, but with no output schema and minimal invocation requirements, that is a minor gap rather than a blocking one.

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

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

The tool has zero parameters, so the schema supplies 100% of parameter information without the description needing to compensate. Baseline 4 is appropriate; there is no param semantic gap to fill.

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 title provides a clear verb and resource ('Discover the MCP settings, entitlements and schemas') and the description specifies the concrete contents ('Effective entitlements, JSON schemas and examples'). It stands apart from the many mutation and specific get/list siblings because it is framed as the read-before-configuring discovery tool, though the description itself lacks an explicit fetch/return verb.

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

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

The description gives an explicit usage trigger: 'Read before configuring'. This is clear context that the agent should call this before any update/set/publish operations. It does not explicitly name alternatives or exclusions relative to sibling tools, but the 'before configuring' framing sufficiently routes it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not repeat those. It adds value by stating the results are aggregated and that contact details are deliberately withheld, which informs the agent about the nature of the output. However, it does not disclose potential error conditions, rate limits, or other behavioral nuances.

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 concise sentence, front-loading the core purpose. It is appropriately brief, but it omits critical details such as parameter explanations and usage context, making it under-specified rather than efficiently complete.

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 two parameters and no output schema, the description is too minimal. It does not explain what 'reads and contacts' means, what the statistics look like, or how the days parameter affects results. The lack of output schema makes the description the only source of return-format information, and it is absent.

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

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

The schema has 0% description coverage, and the description provides no explanation of the parameters (catalogue_id, days). It does not clarify that days controls the aggregation window or that catalogue_id selects which catalogue's stats are returned. The description offers zero semantic help for the parameters, leaving the agent to guess from names and defaults.

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 aggregated statistics (reads and contacts) and explicitly notes it does not disclose contact details. The verb 'read' and resource 'statistics' are specific, but it does not differentiate from sibling tools like foliade_catalogue_status, which likely provides status rather than statistics. The privacy note adds useful specificity.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention foliade_catalogue_status or any other sibling that could be confused with it, nor does it provide exclusions or prerequisites. The agent is left to infer usage from the name and title alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds a valuable operational detail: the tool cannot be called with just the public link; it requires owner OAuth or guest token. This goes beyond the annotations without contradicting them, giving an agent a concrete precondition for successful invocation.

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 sentence with no filler, and it immediately conveys the most important constraint. It is appropriately brief, though it starts with a behavioral note rather than the purpose, which may reduce front-loading of what the tool actually does.

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

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

With no output schema and no information about return values, the description is incomplete for an agent deciding what to expect. It doesn't mention what 'conversion' or 'state' means operationally, how to interpret the result, or any failure modes beyond the auth note. For a status-checking tool, this is a significant 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 0%, so the description must compensate for both parameters. It clarifies that guest_token is a form of auth and that the public link alone won't work, but it says nothing about catalogue_id or how the two interact. The title hints at catalogue_id's role, but the description leaves a large semantic gap for a required parameter.

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 title clearly states the tool checks catalogue conversion and state, but the description itself only mentions an authentication requirement and doesn't restate or refine the purpose. It also doesn't distinguish this tool from the similarly named sibling foliade_catalogue_stats, leaving ambiguity about which one to choose.

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 a usage constraint: private state requires owner OAuth or guest token, and the public link alone is insufficient. This implies when auth is needed but gives no guidance on when to prefer this tool over alternatives like foliade_catalogue_stats or foliade_get_catalogue_settings, so usage context is only partially covered.

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

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

No contradiction with annotations; readOnly=false and destructive=false are consistent with creating an unpublished draft. The description adds the plan requirement and the no-auto-publish side effect, but it doesn't mention error behavior, access/visibility of the draft, or how to locate the created shelf afterward.

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

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

Two short sentences with no filler; the core behavior is front-loaded and the plan requirement is stated in a single clause. This is an efficient description.

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 creation tool with a large ShelfPatch object, no output schema, and 0% parameter coverage in the description, this is too thin. It tells the agent the draft state and plan requirement but not what to pass in the patch, what success returns, or what follow-up calls (e.g., publish) are 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 description coverage is 0% and the description adds nothing about the 'name' or 'patch' parameters. The 'patch' parameter is especially unclear: an agent isn't told that it is a ShelfPatch of settings to apply to the new shelf, and the French property names in the schema are left unexplained.

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

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

States a specific action and resource ('Creates a shelf') and clarifies the created object's state ('as a draft', 'nothing is published automatically'). This distinguishes it from update/publish/list siblings by operation, though it doesn't explicitly name an alternative and doesn't carry the title's 'private' qualifier into the description.

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

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

Provides a clear precondition ('Distributeur plan is required') and sets the expectation that publication is a separate step. It never explicitly contrasts this with foliade_update_shelf or foliade_publish_catalogue, so the when/why to choose it is mostly implied by the verb 'Creates'.

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

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

Annotations already mark the operation as non-read-only and non-destructive, and the description adds useful context about plan limits and capturing existing styling/media. It does not disclose behaviors like failure when expected_revision is stale or what happens if plan capacity is exceeded, but the annotations lower the burden.

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

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

The description is a single front-loaded sentence with no filler. Every phrase, including 'existing styling and media', 'as a theme', and 'within the limit of the plan', contributes meaning.

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

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

For a mutation tool with 3 required parameters, no parameter descriptions, and no output schema, the description leaves a critical unknown (expected_revision) and gives no sense of return values or plan-limit behavior. It is not complete enough for an agent to construct a correct call confidently.

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

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

Schema description coverage is 0%, and the description only indirectly clarifies catalogue_id (the catalogue whose styling/media is saved) and possibly name (the resulting theme's name). expected_revision is completely unexplained despite being required with a 64-character hex pattern, so the description does not compensate for the schema's lack of parameter documentation.

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 ('Saves') and resource ('existing styling and media of the catalogue') and clearly frames the result as a theme. It distinguishes from likely siblings like apply_theme and update_theme by emphasizing creation from a catalogue, though it does not explicitly name those alternatives.

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

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

The description implies the intended scenario: you have a catalogue whose current styling/media you want to preserve as a theme, subject to plan limits. It gives no explicit guidance about when to use this tool versus apply_theme or update_theme, leaving the agent to infer selection from the title and verb.

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

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

Annotations already indicate it is non-read-only and non-destructive. The description adds value by specifying that no email is sent and the catalogue is not published, which clarifies side effects beyond the basic mutation. This goes beyond the annotations and helps agents understand the operational behavior. No contradictions with annotations.

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

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

The description is exceptionally concise: two short sentences, no unnecessary words. The primary action is front-loaded, and the exclusions are clearly stated. It earns a perfect score for efficiency and structure.

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 4 parameters (2 required) and no output schema, the description is inadequate. It fails to explain parameter semantics, expected input values, or what the tool returns after creating the link. An agent cannot reliably invoke this tool without additional knowledge, making the description incomplete for the tool's complexity.

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

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

Schema coverage is 0%, so the description must explain the parameters. It does not mention note, email, recipient, or catalogue_id at all. The description says 'named Business link' but does not clarify which parameter corresponds to the name. Agents have no guidance on what these parameters mean or how to fill them correctly, making this a severe gap.

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

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

The description clearly states the tool creates a named Business link (tracking link) and explicitly clarifies it does not send email or publish the catalogue. This differentiates it from siblings like update_tracking_link and publish_catalogue. The verb 'creates' plus the resource makes the 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 provides clear exclusions ('No email is sent; does not publish the catalogue'), which tells agents when NOT to use this tool. It gives context about the scope, but it does not explicitly name alternative tools or specific conditions for when to use this one instead. The guidance is present but not fully explicit, so a 4 is appropriate.

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

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

The description adds real behavioral value beyond the annotations. It translates the idempotentHint into a concrete guarantee ('never a duplicate'), and it discloses asynchronous conversion and private-by-default visibility — both absent from the annotations. readOnlyHint=false and destructiveHint=false are consistent with 'finalises' and the repeat-safety claim, so there is no contradiction.

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

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

Three short sentences with no filler; each earns its place: the core action, the idempotency guarantee, and the async-plus-privacy caveats. The most operationally critical information (check status, private until published) appears early and compactly.

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

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

For a simple 2-parameter tool with no output schema, the description covers the essential operational behaviors: what finalizing does, repeat safety, the async handoff to foliade_catalogue_status, and the follow-up publish step. Remaining gaps are the unexplained guest_token parameter and no indication of what the call returns, so it is adequate but not 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 0%, so the description carries the burden of explaining the parameters, but it does not define upload_id or guest_token at all. upload_id's role is weakly inferable from 'an upload that has been received', but guest_token's purpose and when to supply it are completely unexplained. With zero schema coverage, this is a clear gap.

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

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

The title provides a specific verb-resource statement ('Convert the uploaded PDF into a draft'), and the description's 'Finalises an upload that has been received' aligns with it. This is distinguishable from siblings such as foliade_prepare_upload (upload intake) and foliade_publish_catalogue (making public). However, the description itself never names or contrasts those siblings, and 'finalises an upload' is somewhat generic without 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 conveys workflow context: it applies to an upload that has already been received, the result must not be treated as final until foliade_catalogue_status is checked, and the catalogue remains private until published explicitly. This effectively routes the agent through the prepare→finalize→status→publish pipeline, though it never explicitly names alternatives or states when-not-to-use the tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds useful scope by stating the exact fields returned (brand name, colour, default PDF download) and what is excluded (billing information), which goes 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 a short, efficient fragment that lists the three included fields and one exclusion without wasted words. It could be more structured as a full sentence, but it is front-loaded and each term earns its place.

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

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

For a zero-parameter, read-only getter, the description covers the essential response content and exclusion, which is sufficient. It does not specify return formatting, but with no output schema and no params, this is a minor gap and acceptable.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and there is no missing information about arguments.

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 lists the specific brand settings returned (name, colour, default PDF download) and explicitly excludes billing information, making the tool's scope clear. It is distinct from sibling tools like update_brand or apply_theme, though the description itself lacks a verb, relying on the title 'Read the account brand settings' for the action.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The exclusion of billing information is the only contextual hint, but no alternative tools or selection criteria are mentioned, leaving the agent to infer usage from the name and title.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds two useful traits: it returns 'protection without secrets' (implying sensitive data is not exposed) and the revision required for subsequent changes. These go beyond structured data. It's cryptic but not contradictory.

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

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

The description is brief (one list), but it's under-specified rather than concise: it's a fragment that omits the verb and reads like telegraphic notes. It doesn't front-load a clear statement of what the tool does.

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

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

For a one-parameter read-only getter with no output schema, the description should clearly state what it returns and how to use it. It lists some return categories but leaves catalogue_id semantics unexplained and the 'revision' mechanism vague. The description feels incomplete.

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

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

Schema description coverage is 0% and the description never mentions catalogue_id, its format, or its semantics. The schema only gives name/type/pattern. The description does nothing to help an agent construct the parameter correctly.

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 title states 'Read every reader and catalogue setting' and the description lists setting categories, so the verb+resource is identifiable. However, the description is a fragment rather than a sentence, and 'every reader' is ambiguous; it doesn't clearly differentiate itself from other getter tools like foliade_catalogue_status or foliade_get_shelf.

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?

No explicit when-to-use or when-not-to-use. The 'revision needed for changes' hints that this should be called before mutations, but the description doesn't name alternatives or conditions. An agent has to infer the tool's role in a workflow.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds little behavioral context beyond that. The phrase 'The files remain those of the catalogue' hints that this operation doesn't change files, which aligns with readOnlyHint, but it's vague. No contradiction, but no rich behavioral disclosure either.

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 very short (two fragments), which is concise, but it's under-specified rather than efficiently informative. The title is more informative than the description, which is a structural problem. The description front-loads 'Elements' which is unclear.

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 tool with one parameter and no output schema, the description should clarify what the return value contains. The title mentions 'interactive draft, suggestions and history' but the description says 'Elements, published version, differences and revision' – these are different concepts. The agent cannot reliably know what this tool returns or how to use it. The 'files remain those of the catalogue' sentence adds confusion rather than clarity.

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

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

Schema description coverage is 0%, so the description must compensate. The only parameter is catalogue_id, which is self-explanatory from its name and pattern, but the description doesn't explain how catalogue_id relates to the returned enrichments. The description's 'The files remain those of the catalogue' suggests catalogue_id identifies the catalogue, but it's not explicit. With 0% coverage, the description should at least map the parameter to the operation.

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 title says 'Read the interactive draft, the suggestions and its history' which is clearer than the description, but the description itself is vague: 'Elements, published version, differences and revision. The files remain those of the catalogue.' It does not state a clear verb+resource. 'Elements' and 'differences' are ambiguous, and the second sentence about files is confusing. The tool name 'foliade_get_enrichments' suggests retrieving enrichments, but the description doesn't clearly say 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?

No guidance on when to use this tool versus alternatives. Siblings like foliade_update_enrichments, foliade_publish_enrichments, foliade_restore_enrichments exist, but the description doesn't differentiate. The title mentions 'interactive draft, suggestions and history' but the description doesn't explain when to call this vs foliade_get_catalogue_settings or foliade_catalogue_status.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds small behavioral clues by mentioning 'catalogues in order' (ordered output) and 'revision of the shelf' (returned version data), but it does not describe auth needs, not-found behavior, or any side effects beyond what the annotations convey.

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

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

The description is very short and not wordy, but it is a fragment that lacks a verb and reads like a list of returned fields. It is concise in length, but the structure does not front-load the action or make the tool's behavior instantly graspable.

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 get-by-id tool with annotations covering safety, the description gives some indication of return content (settings, catalogues in order, revision). However, with no output schema and no explicit statement of what a shelf is or what the response structure looks like, the definition is only minimally complete for an agent 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?

There is one parameter, shelf_id, and schema description coverage is 0%. The description never mentions shelf_id or explains how to identify the shelf, so it adds no semantic value beyond the schema's field name and pattern.

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 title 'Read a shelf and its contents' supplies a specific verb and resource, and the name foliade_get_shelf aligns with this read operation, distinguishing it from list/create/update shelf siblings. However, the description body is an awkward noun phrase ('Settings, catalogues in order, and revision of the shelf') rather than a clear action statement, so it does not fully clarify purpose on its own.

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?

No guidance is provided on when to use this tool versus alternatives like foliade_list_shelves for listing shelves or foliade_update_shelf for modifying one. The read-only intent is implied by the name/title/annotations, but the description gives no explicit context, prerequisites, or exclusions.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description adds meaningful merge semantics with 'merges ... without duplicates.' Still, it does not disclose side effects on an existing table of contents, the role of expected_revision, or what happens with dry_run.

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 sentence with no filler, and 'without duplicates' adds useful behavioral detail. It is appropriately concise, though it could have used its brevity to cover more of the parameter semantics.

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

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

With no output schema and sparse annotations, the description carries a heavy burden, but it omits prerequisites, the effect on existing TOC entries, and the meaning of expected_revision and dry_run. This is insufficient for a mutating import tool.

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

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

Schema description coverage is 0% and the description mentions none of the three parameters. It does not clarify catalogue_id, expected_revision, or dry_run behavior, leaving the agent to rely solely on parameter names and patterns.

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 ('Merges') and names the resource ('PDF bookmarks' into 'table of contents'), adding the useful 'without duplicates' guarantee. It is clearly not a generic operation, though it does not explicitly differentiate itself from the sibling foliade_set_chapters.

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

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

The description implies a use case: when PDF bookmarks should be merged into the table of contents. However, it provides no explicit when-to-use or when-not-to-use guidance, and it does not mention any alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety. The description adds context about the account scope and pagination, which is useful. However, it does not disclose any other behavioral traits like rate limits or return format. Given the annotations, this is adequate but not rich.

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

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

The description is a single, clear sentence that immediately states the action and scope. It is front-loaded with the core purpose and mentions pagination succinctly. 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 simple list tool with two optional parameters and no output schema, the description covers the account scope and pagination. However, it does not describe what the returned data looks like (e.g., catalogue objects or IDs), which is a gap given the absence of an output schema. The annotations cover safety, so the description is reasonably complete but leaves room for improvement.

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 0% – the description does not explain the 'limit' and 'offset' parameters. Although it mentions pagination, which implies these params, it does not describe their semantics or defaults. With a schema that only provides type and title, the description should compensate but fails to do so adequately.

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 'Lists', the resource 'catalogues', and the scope 'private and public' of the connected account. It also mentions pagination, which is a distinguishing feature. This differentiates it from sibling tools like foliade_catalogue_stats (which provides stats) or foliade_catalogue_status (status), so an agent can identify the correct 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 provides no guidance on when to use this tool versus alternatives such as foliade_catalogue_stats or foliade_get_catalogue_settings. It does not mention any exclusions or conditions for selection. With many sibling tools, this lack of routing guidance is a notable gap.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: results are paginated, and passwords are deliberately omitted from the response. 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?

A single, tightly written sentence that front-loads the core purpose ('Paginated list of the shelves and their settings') and appends the important redaction detail ('without passwords'). 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 low-complexity, read-only list operation with annotations covering safety, the description is mostly sufficient. It states pagination, content scope, and sensitive-data exclusion. However, with no output schema, it could briefly note what kinds of settings are returned or how pagination behaves, though this is not a critical 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 0%, so the description carries some burden. 'Paginated' implies that limit and offset control result chunking, which adds minimal meaning beyond the self-explanatory parameter names and schema constraints. However, it does not clarify defaults, maximums, or the effect of each parameter beyond what the schema already states.

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

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

The description uses a specific verb and resource: 'Paginated list of the shelves and their settings.' It clearly identifies the object category (shelves) and distinguishes itself from sibling list tools like foliade_list_catalogues, foliade_list_themes, and foliade_list_tracking_links. The qualifier 'without passwords' adds a useful scope clarification.

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

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

The description implies a listing use case but gives no explicit guidance on when to choose this tool over foliade_get_shelf (single shelf retrieval) or how it relates to shelf creation/updating tools. Sibling alternatives exist, but no conditions or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds a domain fact that themes are copies, not live links, which provides some context about the nature of the data but does not describe the tool's behavior beyond what annotations already convey. This is minimal added value, so 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 a single sentence and is concise, but it is under-specified. It does not front-load the core purpose (listing themes) and instead provides a tangential domain note. The sentence does not earn its place because it lacks essential information.

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

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

The tool is a simple paginated list operation, but the description omits the core function entirely. It does not state that it lists themes, nor does it mention pagination or any return information. With no output schema, the description should at least clarify what the tool returns, but it does not.

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

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

Schema description coverage is 0%, meaning the limit and offset parameters have no descriptions. The description does not mention or explain these parameters at all, failing to compensate for the schema gap. An agent would not know what limit and offset control or their valid ranges.

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 does not state the action of listing or retrieving themes. It only describes themes as 'Account themes, their settings and revisions; a theme is a copy, not a live link.' The name and title imply listing, but the description itself is vague about the tool's function, making it hard for an agent to know what it 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?

There is no guidance on when to use this tool versus alternatives. It does not mention any conditions, exclusions, or sibling tools. The description provides no context for when listing themes is appropriate.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds meaningful behavioral context beyond annotations: it discloses that the response contains recipient information and instructs not to disclose it publicly — a privacy caveat that is not present in the structured data. It also notes the links are scoped to the account, which is useful. This exceeds the annotation baseline.

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

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

The description is short and contains no filler, but it is structurally awkward: the first sentence is a fragment ('Named links of the catalogue owned by the account') rather than a complete declaration. It does front-load the resource but not the action. The privacy note is useful but could be integrated more clearly.

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 output schema, the description should clarify what the tool returns. It does mention 'named links' and 'recipients', which hints at the response, but it omits pagination behavior (limit/offset), any mention of required parameters, or details about the link structure. For a simple listing tool this is adequate but not fully complete.

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

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

Schema description coverage is 0%, and the description provides no information about any parameter. It does not mention catalogue_id, limit, or offset, nor their meanings or constraints. With zero schema documentation, the description compounds the gap and leaves the agent to infer parameter semantics from names and types alone.

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 is a noun phrase — "Named links of the catalogue owned by the account" — it does not state an action like 'list' or 'retrieve'. It relies entirely on the tool name and title to convey the operation. It is not a tautology, but it is vague and does not tell the agent what the 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?

No guidance on when to use this tool versus alternatives. There is no mention of when to prefer listing over creating or updating tracking links, nor any contextual cue such as 'use this to fetch existing links'. The description is silent on usage scenarios.

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 meaningful behavioral and security context beyond the annotations: the deposit is single-use, expires in 10 minutes, allows no reading, is not an account API key, and the returned headers must not be published. This is exactly the kind of context an agent needs.

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

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

Four tight sentences, front-loaded with purpose and action, followed by transfer mechanics and a security warning. No filler or redundancy.

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

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

The description covers the lifecycle, required computations, transfer mechanics, and security obligations, and it references upload_url and returned headers despite having no output schema. It leaves optional parameters and the follow-up finalize step unmentioned, but the core invocation is fully navigable.

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

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

With 0% schema description coverage, the description compensates for the core required parameters: size_bytes and sha256 are tied to 'Compute the size and the SHA-256 of the local PDF', and filename is implied. However, optional parameters like title, language, guest_mode, and notice_version receive no explanation.

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 ('Creates a single-use 10-minute deposit') and a concrete workflow (compute size/SHA-256, transfer bytes via PUT), which clearly identifies this as the upload-preparation step and distinguishes it from siblings like foliade_finalize_upload.

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 procedural context: compute the PDF size and SHA-256, then PUT the bytes to upload_url. It does not explicitly name alternatives or when-not conditions, so it stops short of a 5.

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

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

Annotations already declare idempotentHint=true and readOnlyHint=false; the description adds genuinely useful context: the requirement of explicit user request and the guarantee that the identifier is preserved. This goes beyond the structured data and does not contradict the annotations.

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

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

Two terse sentences front-load the main effect and a key caveat. Every word earns its place; this is appropriate brevity, not under-specification.

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

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

For a simple two-parameter publish operation, the description covers the primary effect and persistence of the identifier. However, it omits workflow prerequisites (e.g., draft state, finalized upload) and the meaning of guest_token, and with no output schema the agent gets no return-value 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 description coverage is 0%, so the description must carry the parameter-meaning burden, but it adds no parameter-level detail. It implies catalogue_id is the identifier yet never explains guest_token (default ''), leaving one of two parameters effectively undocumented.

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

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

The description states the core action ('makes the catalogue public') and the resource (the catalogue), and the title anchors it to publishing an existing draft. It is clearly distinct from the sibling unpublish_catalogue by direction of the action, though it does not explicitly contrast with set_catalogue_access.

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 only guidance is 'on explicit request only,' which is a consent precondition rather than a when-to-use-versus-alternatives signal. No sibling tools are named (e.g., unpublish_catalogue or set_catalogue_access), so an agent must infer when to select this tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds useful context by saying publishing includes history and excludes the catalogue, but it does not explain what publishing replaces, overwrites, or how expected_revision protects against conflicts.

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

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

Two short sentences with no filler. The main action and the key exclusion are front-loaded, making the description easy to parse quickly.

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

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

The description is too sparse for an agent to call this tool correctly: it lacks parameter semantics, does not explain the required expected_revision, and does not clarify what 'with history' means operationally. The destructive annotation helps, but the description still leaves important behavioral gaps.

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

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

Schema description coverage is 0% and the description does not mention catalogue_id or expected_revision at all. The required revision parameter is especially important because its meaning as a validation or concurrency token is not conveyed anywhere in 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 uses a specific verb ('Publishes') and resource ('interactive elements'), and explicitly states it does not publish the catalogue itself. This clearly distinguishes it from the sibling foliade_publish_catalogue.

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 its scope by saying it does not publish the catalogue, which hints that foliade_publish_catalogue is the alternative. However, it does not explicitly state when to choose this tool over related tools like foliade_update_enrichments or foliade_restore_enrichments.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is established. The description adds that a new history entry is created and that some plan re-checking occurs, which is useful. However, it does not disclose what gets overwritten, whether the restore is reversible, or what happens if the expected revision does not match.

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

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

The description is compact, front-loads the main verb, and contains no filler. Minor deduction for the vague phrasing 'this catalogue' and 'the plan', and for combining two ideas in a semicolon-heavy sentence, but overall it is economically written.

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 three required parameters and no output schema, an agent needs to know what expected_revision means, how to obtain it, and what the restore actually changes. The description only gives a high-level action and a side effect, leaving significant operational and prerequisite gaps.

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

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

Schema description coverage is 0%, and the description does not explain any of the three parameters. catalogue_id, publication_id, and expected_revision are left entirely to the raw schema names and patterns, so an agent cannot understand what 'expected_revision' refers to, where it comes from, or how it relates to the restore plan.

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 ('Restores') and a resource ('a version of this catalogue'), and adds a side effect ('creates a new history entry'), which clearly conveys the core action. It does not explicitly differentiate from sibling tools like foliade_publish_enrichments or foliade_update_enrichments, but the restore action is distinct enough that an agent can infer the tool's 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?

There is no when-to-use or when-not-to-use guidance, no mention of alternatives, and no explanation of what 're-checking the plan' entails or when it is required. The only implicit signal is that this is a restore operation, which is not enough for an agent to reliably choose it over similar enrichment-related tools.

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

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

The description adds several behavioral notes beyond annotations: it never publishes a draft, never returns the password, and domain declaration does not configure DNS/TLS. These are useful and not contradicted by annotations (destructiveHint true).

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 brief and has no filler, but it is not front-loaded with the main purpose; it opens with a caveat rather than the core function. Structure could be improved by leading with 'Sets catalogue protection and addresses'.

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, open-world tool with 7 parameters and no output schema, the description is incomplete. It lacks parameter semantics, return value expectations, and usage context compared to alternatives.

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

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

With 0% schema description coverage, the description provides no explanation of any of the 7 parameters. The agent has to rely solely on the schema's type/enum/default info, which is insufficient for parameters like 'expected_revision' or 'domaine'.

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 says 'Changes access on explicit request only' but does not state the resource (catalogue) or the specific operation (setting protection and addresses). The title is clear, but the description is vague, so an agent may not know exactly what it 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?

No guidance on when to use this tool versus siblings like foliade_publish_catalogue or foliade_set_shelf_access. It only hints that it should be used on explicit request, but does not compare with alternatives.

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

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

Annotations already mark this as destructive and not read-only. The description adds meaningful behavioral context: it replaces the entire table of contents, preserves order, and removing it via an empty list. This goes beyond the structured annotation hints.

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

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

A single, front-loaded sentence conveys the core action and the edge case (empty list removes the TOC). There is no filler or redundant restatement of the title.

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

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

For a destructive tool with an expected_revision parameter, dry_run flag, and no output schema, the description lacks essential operational details such as concurrency semantics, dry-run behavior, and parameter roles. The tool can be invoked correctly only with substantial inference.

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

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

Schema description coverage is 0%, so the description must compensate for the four parameters. It only alludes to the chapters list ('ordered list') and empty-list behavior, but does not explain catalogue_id, expected_revision, or dry_run. The agent must infer their meaning entirely from names and constraints.

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

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

The description names a specific verb ('Replaces') and resource ('the table of contents'), and clarifies the effect of an empty list. It is clear what the tool does, though it does not explicitly differentiate itself from the sibling foliade_import_chapters.

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 no guidance on when to use this tool versus alternatives such as foliade_import_chapters. It states the replacement behavior but no context about prerequisites, preferred scenarios, or when not to call it.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation/destructive nature is covered. The description adds context by naming the exact configuration aspects changed and the plan/email prerequisites. It does not go deeper into side effects, concurrency implications, or what is overwritten, but the annotation coverage 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?

Two compact sentences, with the primary purpose front-loaded and the key prerequisites in the second sentence. There is no filler or redundant restatement of the schema.

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

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

With no output schemaainer and no parameter descriptions in the schema, the description should provide enough operational context to invoke the tool safely. It explains the patchable fields and one prerequisite, but leaves expected_revision's optimistic-concurrency role, catalogue_id's purpose, dry_run behavior, and return expectations unexplained. This is insufficient for a mutation tool with required identifiers and a destructive hint.

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

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

Schema description coverage is 0%, so the description must compensate. It does map some patch fields ('activation', 'page', 'blocking mode', 'fields', 'consent') to human-readable meanings, but it says nothing about the required parameters catalogue_id, expected_revision, or dry_run. For a tool with three required parameters, this is an incomplete semantic bridge.

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

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

The description clearly states the action ('Sets') and identifies the resource (lead capture configuration), enumerating the aspects it controls: activation, page, blocking mode, fields, and consent. It does not explicitly distinguish itself from sibling set_* tools, but the resource and field list make 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 practical usage constraints: a lead-capture plan is required and email is mandatory. However, it does not explain when to prefer this tool over alternatives, nor does it mention when not to use it, leaving the routing decision mostly to the agent's 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=false and destructiveHint=true. The description adds two behavioral constraints: it only changes access on explicit request, and it does not manage DNS/TLS. These are useful but minimal additions, and no contradictions are present.

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 short sentence, but it is cryptic and not front-loaded with actionable information. The qualifier 'on explicit request only; DNS/TLS remain separate' is placed after the main clause and does not clarify the tool's core 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?

With 8 parameters, no output schema, and only a vague one-sentence description, this is severely incomplete. The annotations carry the safety profile, but an agent cannot know what states mean, how protection works, or what expected_revision is for. Major operational detail is missing.

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

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

Schema description coverage is 0%, and the description provides no meaning for any of the 8 parameters. It does not explain the state enum (brouillon, public, protege), protection, password, domaine/sous_domaine, dry_run, or expected_revision. The description fails to compensate for the empty 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 title 'Publish, protect or close a shelf' states a specific verb and resource, and the description clarifies it controls publication/access. It reasonably distinguishes from sibling tools like foliade_set_catalogue_access by targeting 'shelf' rather than 'catalogue'.

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?

No explicit guidance on when to use this tool versus alternatives such as foliade_publish_catalogue or foliade_set_catalogue_access. The only hint is 'shelf' in the title, and the description's 'explicit request only' is too indirect to serve as usage direction.

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

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

Annotations already mark this as a destructive write operation, and the description adds meaningful nuance: 'Replaces the contents of the shelf' while 'The PDFs themselves are kept.' This clarifies what is destroyed and what is preserved, going beyond the raw destructiveHint annotation. No contradiction with annotations is present.

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

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

Two sentences with no filler. The primary action is front-loaded in the first sentence, and the second sentence efficiently adds an important safety clarification. Every part earns its place.

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

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

For a destructive tool with a required `expected_revision` and a `dry_run` option, this description is incomplete: it never mentions how to obtain or use the revision, what dry-run mode does, or what success/failure looks like. The absence of an output schema makes the missing behavioral details more significant. It is a concise description but not a complete calling contract.

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

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

Schema description coverage is 0%, so the description must compensate, but it only hints at the semantics of `items` as an 'ordered list with collection names.' It does not explain the required `expected_revision` field, the `dry_run` flag, or how `shelf_id` should be supplied. The required concurrency and preview parameters are left entirely to inference from their field 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 uses a specific verb and resource: 'Replaces the contents of the shelf with this ordered list with collection names.' It clearly distinguishes this from generic shelf operations like foliade_update_shelf by focusing on catalogue composition and ordering. The added clarification that PDFs are kept further sharpens the 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 gives no explicit guidance about when to use this tool versus alternatives such as foliade_update_shelf, foliade_set_shelf_access, or foliade_create_shelf. The intended use is only implied by the operation itself, with no when-to-use or when-not-to-use conditions.

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

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

Annotations already mark destructiveHint=true, but the description adds crucial context that data is not deleted—only the public link is closed. It also notes an explicit request is required, which is not in annotations. This adds transparency beyond the schema and aligns with openWorldHint but 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?

The description is two short sentences with no fluff. The primary action is front-loaded, and the additional note about explicit request is placed second. It is appropriately brief for a simple operation.

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

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

The description covers the outcome but omits parameter semantics entirely. It also doesn't clarify the role of guest_token or provide prerequisites (e.g., must be published first). Given schema coverage is 0%, the description should have compensated, but it leaves critical details unexplained.

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 0% and the description does not explain either parameter (catalogue_id or guest_token). The agent gets no help understanding what these parameters mean or how to fill them. The description fails to compensate for the lack of schema documentation.

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 closes the public link for a catalogue, distinguishing it from sibling tools like foliade_publish_catalogue (the inverse) and deletion tools. The verb 'closes' plus the resource 'public link' gives a precise action.

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 no guidance on when to use this tool versus alternatives. It does not mention foliade_publish_catalogue or any other conditional context. The statement 'Requires an explicit request' is a precondition, not usage guidance. It leaves the agent to infer when unpublishing is appropriate.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's 'Account-wide impact' adds useful context about the scope of the mutation. However, it does not elaborate on consequences, reversibility, or permission requirements, which would be valuable given the destructive hint. It adds some value beyond annotations but not rich behavioral detail.

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

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

The description is a single sentence with no fluff, and the key point ('Account-wide impact') is front-loaded. It is concise and well-structured, though it sacrifices substance for brevity.

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 nested patch object with three properties, a dry_run flag, and an expected_revision parameter, plus no output schema, the description is severely incomplete. It does not explain what the patch affects, how dry_run works, or what expected_revision is for. An agent cannot confidently construct a correct call without additional documentation.

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

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

Schema description coverage is 0%, and the description provides no information about the parameters (patch, dry_run, expected_revision). The schema only gives types and patterns, with no semantic guidance. The agent is left to guess what 'patch' should contain, what 'dry_run' does, and what 'expected_revision' is for. This is a severe gap.

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

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

The description does not explicitly say 'update brand' but the title does, and the description's 'Account-wide impact' and 'global customisation' convey the resource and scope. It also differentiates from update_catalogue, so the purpose is clear enough for an agent to identify 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 explicitly states when to use this tool ('global customisation') and when to prefer an alternative ('prefer update_catalogue for a single PDF'). This is clear, actionable guidance that helps the agent select the right tool.

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

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

The description adds meaningful behavior beyond the annotations: PATCH-style semantics ('Changes only the fields supplied'), dry_run performing no write, and no change to publication state. This is valuable context, especially since the tool is marked destructive. It still does not address expected_revision conflict behavior, but it goes well beyond what the annotations alone reveal.

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

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

The description is short and front-loaded, with the key PATCH behavior stated first and no filler. The category list is somewhat vague, but the overall structure is economical and readable.

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 a nested 30-field patch object, a required revision parameter, and destructive annotations, this description is not complete enough for an agent to call it confidently. The dry_run and publication-state notes help, but they do not compensate for missing field mapping, revision semantics, or guidance on what a valid patch looks like.

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

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

With 0% schema description coverage, the description must carry parameter meaning, but it only provides broad categories rather than mapping to actual schema fields. It does not explain required parameters like catalogue_id or expected_revision, nor does it clarify how the patch object should be structured, leaving the agent to infer too much from French property 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 uses a specific verb and resource: 'Changes only the fields supplied' and then lists affected areas such as colours, bar, controls, sound, reading, logo, title, language, and PDF. This makes the tool's purpose as a partial catalogue-reader/metadata update reasonably clear, though it does not explicitly differentiate it from nearby siblings like foliade_update_theme or foliade_get_catalogue_settings.

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?

No guidance is given about when to use this tool versus alternatives, such as theme updates, enrichment updates, or publication tools. The only usage-related detail is the behavior of dry_run, which is a parameter hint rather than tool-selection guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds meaningful context: the operation replaces the existing draft, accepts only valid/plan-open elements, and has no publishing side effect. This goes beyond the annotation flags and clarifies the destructive scope.

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 action ('Replaces the draft'). It packs the element type list, validation rule, publication boundary, and a pointer to examples into a few lines. Minor formatting awkwardness and the ambiguous '13 types' list prevent 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?

The description covers the tool's purpose, validation constraints, and relationship to publishing, which is good for a destructive draft update. However, it omits the meaning of expected_revision (likely an optimistic-locking requirement) and dry_run, both of which matter for correct invocation. The pointers to other tools help but do not fully close those gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It partially explains the 'elements' parameter by listing accepted types, but it says nothing about catalogue_id, expected_revision, or dry_run. The pointer to get_enrichments/capabilities helps for element structure but does not clarify the tool's own parameters, especially the required expected_revision.

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: 'Replaces the draft' and enumerates the element types (links, buttons, videos, forms, products, galleries, tours, questions). It also differentiates from publish_enrichments by explicitly noting that nothing is published before that separate step, so an agent can distinguish this draft-saving tool from its publishing sibling.

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: this tool replaces the draft, rejects invalid or plan-closed elements, and defers publication to publish_enrichments. It points to capabilities and get_enrichments for examples and structure. It does not explicitly list exclusions or alternative tools, but the relationship to publish_enrichments is clear enough for 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 adds no behavioral context beyond the annotations. It does not mention that the tool overwrites existing settings, requires an expected_revision for optimistic locking, or offers a dry_run mode. Since annotations already declare destructiveHint=true, the description could have added value but fails to do so.

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 extremely short, but it is under-specified rather than concise. It is a list of nouns without structure or explanatory value, failing to earn its place by adding meaningful information for tool selection or invocation.

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

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

Given the complexity of the tool—nested patch object, required revision, optional dry_run, and no output schema—the description is woefully incomplete. It does not address how to use the patch structure, what the revision means, or what happens on success or failure. An agent would have to rely entirely on the schema, which is also sparse on 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?

The description does not explain any of the parameters. With schema description coverage at 0%, the description should compensate by describing key parameters like layout, planche, or the patch structure, but it only lists vague categories. This leaves the agent without any semantic guidance for the many properties.

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 title and description clearly state the tool configures the appearance and reading of a shelf, with the description enumerating specific aspects (texts, six layouts, covers, etc.). This distinguishes it from sibling tools like create_shelf, get_shelf, and set_shelf_access.

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

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

There is no explicit guidance on when to use this tool versus alternatives. It is implied by the name that it updates an existing shelf, but no conditions or exclusions are provided, leaving the agent to infer usage.

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 description does not need to repeat that. It adds some behavioral context by explaining that make_default changes the starting point of new catalogues. However, it does not mention the optimistic concurrency mechanism (expected_revision) or any side effects beyond persistence, leaving gaps.

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

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

The description is very short (two sentences) and front-loads the main action, which is good for conciseness. However, it is under-specified for a tool with six parameters and a nested patch object, so the brevity works against completeness. It is not overly verbose but also not sufficiently informative.

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 three required parameters, no output schema, and no parameter documentation, the description is far from complete. It does not explain how patch interacts with the theme, what expected_revision is for, or when dry_run should be used. An agent cannot confidently call this tool based on the description alone.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only explains make_default, while theme_id, patch, dry_run, and expected_revision are left unexplained. The patch object's many fields are undocumented in the description, making it hard for an agent to know what to pass.

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 it changes a theme, which identifies a specific resource and verb, but it is vague about what exactly changes and does not distinguish it from sibling tools like apply_theme. It mentions make_default explicitly, but the main purpose is under-specified.

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 no guidance on when to use this tool versus alternatives. It does not mention apply_theme for applying themes to catalogues or create_theme for creating new themes, nor does it describe the role of expected_revision or dry_run. The only usage hint is about make_default, which is a parameter, not a usage condition.

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 meaningful behavior beyond the annotations: closing is explicit and reversible, and no message is sent. This usefully refines the destructiveHint: true annotation by reassuring that the action is not irreversible and has no notification side effect. It does not contradict the annotations; it supplements 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?

The description is a single high-density sentence with no filler. It front-loads the action and resource, then adds the most important behavioral caveats. Every clause adds information rather than restating the title.

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

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

This is a mutation tool with 5 parameters, no output schema, and zero schema descriptions, so the description needs to provide substantially more context. It gives a good overview but omits required semantics like the role of expected_revision, how dry_run behaves, and what constitutes a valid patch. An agent would likely struggle to invoke this correctly without additional external knowledge.

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

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

Schema description coverage is 0%, so the description must carry the explanatory burden for parameters. It only maps the patch sub-fields (recipient, note, email, active flag) and completely omits the required top-level parameters catalogue_id, link_id, patch, and especially expected_revision. It also says nothing about dry_run, which is a significant gap for an agent trying to call the tool correctly.

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 ('Changes') with a clear resource ('tracking link') and enumerates the mutable aspects: recipient, note, email, or active flag. This clearly distinguishes it from siblings like foliade_create_tracking_link and foliade_list_tracking_links because it is about altering an existing link. The closing behavior is also directly called out, matching the tool 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 implies when to use the tool—when you need to change an existing tracking link's recipient, note, email, or active flag, or close the link. However, it does not explicitly name alternatives or state when not to use it, such as pointing to foliade_create_tracking_link for new links. The context is implied but not explicit.

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