Cloche

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

Annotations mark it idempotent and destructive; the description goes beyond that by specifying exactly what is destroyed — a different checkpoint replaces the previous one and it is not kept — and confirms the no-publish/no-live-change guarantee. This is the kind of overwrite semantics an agent must know before calling.

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?

Front-loaded with the core action and its bounds, then use conditions, then parameters and overwrite behavior. Dense but every clause carries information; only the work_context field enumeration mildly duplicates 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?

Output schema exists so return values need no explanation, and the description covers the mutation's irreversibility and use triggers. It is slightly thin on the mechanics of recovering a checkpoint later and says nothing about the undocumented development_token, a minor gap for a four-parameter 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 coverage is 75% and the schema already documents every work_context field verbatim, so most of the description's parameter recital is redundant. The one genuine addition is linking base_version to the value returned by get_app_context (0 for an unpublished reservation), which the schema only partially conveys.

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 (saves unfinished work / checkpoint) and immediately bounds scope with 'without publishing or changing the live app,' which cleanly separates it from the publish sibling. An agent can identify the operation without opening the schema.

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

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

Explicitly names two triggering situations: work continuing across turns after reserving an app, and a session ending with unfinished changes. It does not name a sibling alternative by name (e.g. save_record or publish), so routing is inferred rather than spelled out, but the conditions are clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful behavioral detail about how the tool responds in each mode (index vs. matching definitions vs. files) but doesn't mention rate limits, auth needs, or result ordering. With annotations covering safety, this is good 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?

Two compact sentences front-load the purpose, then map each of the three modes cleanly. No wasted words, though adding the 'since' example in the mode list would have tightened it further.

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 an output schema exists and annotations cover safety, the description covers all four parameters and all three usage modes. It doesn't explain what 'organization' does in relation to multi-org users, but that is minor and partly covered by the schema description.

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

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

Schema coverage is 100%; the schema already documents paths, query, since, and organization. The description echoes the modes implied by these parameters and adds a concrete example of 'since' (change id), but doesn't add much syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: returns the organization's own definitions of metrics/terms/rules plus verified queries, naming concrete domains (KPIs, revenue, players, churn, retention). Clearly distinguishable from the sibling 'write_company_definition' since this one returns rather than writes.

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

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

Explicitly says when to use each mode: no input for the index, query for matching definitions, paths for files. This is a complete when-to-use for each parameter combination, leaving nothing to infer.

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

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

Annotations already declare a write-capable, destructive, idempotent, open-world operation, so the bar is lower. The description adds real behavioral detail: the conditional return (connected status plus listed tools and their read-only flags, or a sign-in link for the owner) and that a second address replaces the existing connection. It does not spell out the destructive impact of replacement, but stays consistent 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 content is all relevant, but it is delivered as a run of short, choppy clauses and the key framing ('for an app that shows data from another service') is stranded at the end. Some phrasing ('the name people know it by') is redundant with 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 a full output schema, 100% parameter coverage, and annotations, the description's job is narrow, and it fills it: connection state, the two possible return shapes, and replacement behavior are all covered. Permission/auth prerequisites for the write are the only notable omission.

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

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

Schema coverage is 100%, so the schema already documents url, label, and app_id. The description reframes url as 'the source's https MCP address' and label as 'the name people know it by', which mirrors the schema wording rather than adding new syntax or constraints; baseline 3 applies.

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

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

States a specific verb+resource: it attaches a source to an app, identified by MCP url and label. The closing line 'For an app that shows data from another service' adds domain context. It never names a sibling tool, so an agent must infer differentiation from siblings like get_access or list_apps.

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

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

It notes the tool 'works on an app with no data yet' and implies use when an app needs to read an external service, but there is no explicit when-to-use/when-not and no reference to alternative tools for connecting or configuring access.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true) by enumerating exactly what is destroyed (URL, share links, invitations, stored data), stating no undo, explaining the publish-replaces semantics, failed-publish behavior, and the 'second call not found' signature that confirms success rather than failure. This is unusually rich disclosure for a destructive operation.

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

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

Front-loads the destructive, irreversible fact in the first two sentences, then layers edge cases. Every sentence carries behavioral information, though the closing sentence about the second-call response is convoluted enough to require re-reading.

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?

An output schema exists so return values need no explanation, and the description covers irreversibility, side effects, idempotency semantics, and failure/refusal modes. Nothing an agent needs to call this safely is missing.

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

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

Schema description coverage is 100% and the single app_id is already documented as 'the app to delete, exactly as publish or list_apps gave it'. The description adds no further parameter syntax or format guidance, so the baseline 3 applies.

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

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

States a specific verb and resource ('Deletes an app permanently') and immediately adds the scope of destruction, making it unmistakable against siblings like publish or list_apps. An agent knows exactly what this tool does without opening the schema.

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

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

Provides a clear when-not condition ('An app turned off after a report cannot be deleted, and a retry gets the same refusal') and warns there is no undo, which is strong context for choosing to call it. It does not name a sibling alternative for recovering or archiving an app, so it stops short of explicit 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: links are returned as ids and never URLs, and a person may appear by invite address or by account id depending on whether they have signed in. It says nothing about permissions required to read, but the added identity/ID semantics are genuinely informative.

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

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

Four short sentences, zero filler, with the returned-fields summary front-loaded and the identity caveat placed after it. Slightly dense in clauses, but every sentence carries operational 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?

Even though an output schema exists, the description usefully previews the shape of the result (visibility, links as ids, grants) plus the identity nuance needed to interpret grants. For a single-parameter read tool with annotations and an output schema, nothing an agent needs 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?

With a single parameter at 100% schema description coverage, the schema already defines app_id fully, so the baseline is 3. The description implies the app must be one whose sharing is being read but adds no format, acquisition path, or constraint beyond the schema.

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

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

States a precise verb+resource ('Reads how an app is shared') and enumerates exactly what is returned: public/private visibility, live share links (ids only), and invited people under grants. This is enough to tell it apart from set_access and revoke-grant, which mutate the same resource.

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

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

'For when the person asks who can open an app' gives a clear triggering condition, and 'Giving someone a link means making a new one' steers the agent away from expecting this tool to create links. It does not explicitly name set_access as the mutating counterpart, so it stops short of a full when-not/alternative statement.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description discloses rich edge-case behavior: reserved apps return version 0 with no files, failed apps return the last live version plus a plain problem, stored records are intentionally omitted, and source-backed data returns only a recipe digest and projection, never rows. It also clarifies that ground-truth files/schema win over compact context on disagreement.

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?

It is front-loaded with the core purpose before edge cases, and nearly every sentence carries distinct information (reserved/failed apps, source-backed data, version semantics). It is dense and the final version sentence is a run-on, so it is not maximally tight, but it is largely free of waste.

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

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

Given an output schema exists and the tool's complexity (versioning, reserved/failed app states, source-backed projections), the description covers everything an agent needs to call it correctly and interpret results. Return-shape details are supplementary rather than required.

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 75%, and the description adds real meaning: paths selects from the returned manifest (omit for the full bundle), version reads a past version and carries a publish-safety warning, and app_id is the identifier from the message. development_token is undocumented in both schema and description, a minor gap.

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

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

The description states a precise verb+resource+scope: it returns the complete currently published source of an existing app, keyed by app_id from the user's message. It distinguishes itself from siblings like get_app_status and list_apps by defining exactly what source, schema, and context are 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?

Usage context is clear (call with the app_id in the person's message) and it explains the version parameter's purpose, including a warning that republishing a past version reintroduces a bad publish. It does not explicitly name alternative sibling tools (e.g., get_app_status vs get_app_context) for comparison, so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds real behavioral context beyond them: the discrete state model and the guarantee that nothing stays pending after publish. It does not mention auth requirements or polling behavior, which would have pushed it higher.

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?

Front-loads the return states, which is the most important information, and the routing note follows. The second sentence is a dense em-dash run-on, but no sentence is wasted.

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?

An output schema exists, so return values need not be spelled out, and the description correctly focuses on state semantics and routing. It is essentially complete for a single-parameter status read, with only minor gaps around staleness/polling 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?

Only one parameter (app_id) with 100% schema description coverage, so the schema fully documents it. The description adds no format, source, or lookup guidance for the id beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb+resource ('returns where an app stands') and enumerates the exact returnable states: created/never published, ready, or failed with the reason. It also explicitly distinguishes itself from the sibling `publish`, which returns the final status, so an agent can route between them without opening a schema.

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

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

Gives concrete triggering contexts ('whether their app is up', 'whether a reserved app ever got content') and an implicit exclusion via publish ('publish already returns the final status, and nothing stays pending after it'). It does not mention list_apps or get_app_context as alternatives, but the primary when-to-use is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the scope of returned content (contract, authoring rules, less common publishes, icon rule), but says nothing about behavior beyond that — no auth requirements, no caching, no mention of the unusual idempotentHint=false. 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?

Two short sentences, front-loaded with what is returned before the usage trigger, with no filler. The second sentence is a fragment ('For when you are about to...') that reads slightly awkwardly, keeping it off a 5.

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

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

For a no-parameter, read-only tool with an output schema (which carries the return-shape burden), the description covers purpose, content scope, and a usage trigger. Nothing critical is missing, though it could have named the sibling it complements.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. No parameter meaning is missing or misstated.

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 ('Returns') and concrete resources (the Cloche deploy contract, authoring rules, the icon rule), which is well beyond a restatement of the title. It is implicitly distinguishable from the sibling 'publish' since it returns instructions rather than performing a publish, though it never names that sibling explicitly.

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?

'For when you are about to publish a new app' gives a clear triggering context that an agent can act on, and it implicitly routes away from the sibling 'publish' tool. It stops short of naming alternatives or stating exclusions, so it is not a full 5.

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

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

Annotations already declare readOnlyHint and destructiveHint false, so safety is covered. The description adds genuinely new context beyond them: a sign-in requirement ('like every tool that touches an app'), the fact that app names can collide and app_id disambiguates, and the exact behavior when organization is omitted.

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?

Front-loaded with the action and result, then conditions, then edge cases. Slightly dense in the final sentence, but every clause carries operational information (auth, disambiguation, organization scoping).

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?

An output schema exists, so return values need no explanation. The description covers auth, scope defaults, and the name-collision caveat. Minor gap: no explicit statement of whether the list is paginated or ordered.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema's 'which organization to list; omit to see your personal apps' by explaining what happens to other organizations you belong to when the parameter is omitted, which is real added value.

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 plus the payload (URL and status), which is more informative than a bare 'list apps'. It does not explicitly distinguish itself from near-siblings such as get_app_status or get_app_context, so it stops short of a 5.

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

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

Gives clear triggering conditions: 'For when the person asks what they have, or when you need an app_id you are not already holding.' That second clause implicitly routes callers elsewhere when they already have an app_id, but no sibling is named as the alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: results are scoped to the acting person, private collections show only their own records, pagination terminates with an empty next_cursor, and field values are user-authored.

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 tightly packed sentences with the primary read behavior front-loaded and pagination and collection-mode details following in logical order. Slightly dense—the collection-mode clause is a long second sentence—but nothing is wasteful.

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 paginated read tool with an existing output schema and full annotation coverage, the description covers everything the agent needs: actor scoping, the two operating modes, pagination continuation, and terminal-page behavior. Return values need not be expanded since an output schema exists.

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

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

Schema coverage is 100% and the schema already explains app_id, cursor and collection individually. The description's contribution is mainly restating the mode-switch semantics of collection and cursor, which is mildly useful but largely duplicative of the schema text, so the baseline 3 applies.

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

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

The description names a specific verb and resource (reads an app's data, lists one page of records) and precisely defines scope via the actor ('as the person this call acts for') and the shared/private visibility rule. It distinguishes itself clearly from write siblings like save_record, but never names an alternative tool to steer selection, which keeps it just short of a 5.

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

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

It gives clear conditional guidance: supply a collection to get records, omit it to get the app's declared collections, and pass the previous page's next_cursor to continue. What's missing is any explicit when-not or a pointer to a sibling for adjacent tasks.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds substantial extra context: 'Without base_version a publish replaces every file', 'a stale base is refused', an edit 'miss refuses the publish', 'Files are live only when this call returns ready', and truncated bundles can be detected via bundle_bytes. This goes well beyond what the annotations provide.

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

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

The create/change distinction is front-loaded, but the body is a dense, fragment-heavy wall of text that mixes creation rules, rewrite policy, data_publication mechanics, and return-value notes. For a 20-parameter tool length is defensible, yet many sentences could be trimmed or moved to parameter descriptions for scanability.

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 and the presence of an output schema, the description covers nearly everything an agent needs: create vs change, base_version discipline, assets, schema collections, data_publication, summary/work_context, and rewrite rules. Only minor fields (contract_version, development_token) are left unaddressed, so it is close to 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 90%, so the baseline is 3, but the prose adds cross-parameter meaning the schema cannot: app_id is 'never found by name', base_version is cross-referenced to get_app_context, edits require base_version, and assets require a second publish to PUT bytes. A couple of params (contract_version, development_token) remain unexplained in both places.

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

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

The opening 'Create an app from its files, or change one' states a specific verb (create/change) and resource (app) and immediately splits the two modes. The description also distinguishes this tool from siblings by scope (checkpoint_app saves context when work stops unpublished; get_app_context reads versions) so an agent can route without opening schemas.

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

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

It names alternatives with the condition that selects them: 'To change part of a file, send edits instead of the file', and 'When work stops unpublished, checkpoint_app saves that context'. It also clarifies that an app is identified by app_id from list_apps, and that get_deploy_instructions covers rarer publishes (rename, reserve, share), giving explicit 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?

Beyond the annotations it discloses concrete behavioral traits: field replacement is partial, prior values "are not kept" (destructive consequence), edits are gated by "records they may edit" (permission model), and a repeated no-id call "adds another record" (non-idempotency, corroborating idempotentHint=false). This is rich, non-redundant behavioral context for a mutation tool.

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

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

The add-vs-edit behavior is front-loaded and every sentence carries information about semantics or constraints. It is slightly dense and the two sentences both opening with "With no id" create mild redundancy, but nothing is wasted.

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 five parameters and a non-trivial add/edit duality, the description covers modes, concurrency (etag), destructive partial replacement, permissions, and idempotency. Since an output schema exists, return-value explanation is correctly omitted, leaving nothing essential missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the id/etag pairing and optimistic-concurrency intent, and clarifies that fields "takes only the fields to change" on edit. This goes beyond the schema's field-level descriptions.

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

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

The description states a specific verb and resource ("Saves a record in a collection an app declares") and clearly splits the two operating modes: add when no id, field-level replace when id+etag are supplied. It references list_records for the etag, implying the read/write pairing, but never explicitly names a sibling it is not, so differentiation is inferred rather than stated.

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

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

It gives clear conditions for each mode ("With no id it adds a record", "With an id and the etag list_records gave it, it replaces only the fields sent") and the precondition for the etag coming from list_records. It does not name an alternative tool to use instead or state when not to call it, so guidance is contextual rather than exhaustive.

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

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

Annotations declare destructive=true and idempotent=false, and the description goes well beyond them: it explains that calling link twice yields two live links (a timed-out call may have made one), that revoking an already-revoked link returns a benign 'not a live link' answer rather than an error, that revoke-link does not make the app private or touch other links, and that email invites require a Cloche sign-in with that address. This is exactly the operational context an agent needs for a multi-mode mutation tool.

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

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

The purpose is front-loaded and every paragraph is on-topic, but the text is a ~350-word prose wall with no structure and visible redundancy ('access "signup" opens the app to anyone who signs up, for when the person asked for that' restates the earlier mode list). An agent can use it, but a mode-keyed list would deliver the same content in half the space.

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

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

For an 8-parameter, 8-mode mutation tool with an output schema available, the description covers the remaining gaps: mode selection, prerequisite flows to get_access, error-call semantics, and revocation persistence ('A revoked account stays refused on this app... until invited again'). Nothing essential to correct invocation is missing.

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

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

Schema coverage is already 88%, so the baseline is 3; the description adds real meaning on top, clarifying that a link can never be editor, that a name grant preserves stronger access the account already holds, that link_id from set_access/get_access is required downstream, and that expires governs when a link stops working on its own. It stops short of full per-field coverage (e.g. language and subject_name constraints live only in the schema).

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

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

States a specific verb and resource ('Changes who can reach an app') and then enumerates all eight access modes, so an agent knows exactly what surface this tool controls. It is clearly distinguished from the read-side sibling get_access, which it repeatedly names as the listing counterpart.

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

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

Gives an explicit trigger ('For when the person asks to share, invite, or take that back') and repeatedly routes the agent to alternatives: get_access to list links or grants, set-link-expiry to retime a link, revoke-link vs revoke-grant for the two different removal cases. When-not conditions are also covered, e.g. 'A link can open and save, never change it -- letting someone change it takes an invite'.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, and the description is consistent with them. It adds useful behavioral context beyond the annotations: the two-step lifecycle (bytes stored now, named in assets on the next publish) and the return payload (sha256 and byte count). It does not mention auth requirements or size limits, which is the only gap.

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

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

Three sentences, front-loaded with the core purpose, then the usage condition, then the return behavior. No filler and each sentence carries distinct 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?

Covers purpose, when to use, and the return values despite an output schema existing, and the flow through publish is clear. The only shortfall is guidance around the optional app_id and development_token parameters (auth/scoping), which neither the description nor the partial schema coverage addresses.

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 75%, so the schema largely documents path, app_id, and content_base64 already. The description restates those semantics ('path in the app', 'content as standard base64') without adding format, encoding, or size constraints beyond what the schema says. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Stores one binary file's bytes for a later publish') and immediately distinguishes itself from the publish sibling by scoping to clients that cannot make an HTTP PUT to the signed url publish returns. An agent can tell exactly what this does and how it differs from publish without opening either schema.

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

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

Provides an explicit when-to-use condition: it exists for clients that cannot perform the HTTP PUT to the signed URL that publish returns. This effectively names the alternative (direct upload via publish's signed url) and the condition that selects this tool instead, leaving nothing to inference.

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

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

Goes well beyond the annotations (destructive, non-idempotent, not read-only): it discloses that changes are live for all members at once, that unauthorized paths are refused 'with their name,' the proposed/ workflow, and what the response returns (change, owners, cross-file problems). This is unusually rich behavioral context.

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

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

One dense paragraph, front-loaded with the purpose and effect. Every sentence carries information, though some clauses ('move gives the file the path in to') are terse to the point of awkwardness and could be bulleted for scannability.

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?

Covers the full operational picture: action semantics, permission/ownership rules, the proposal workflow, concurrency via etags, and cross-file validation. With an output schema present, return-value explanation is a bonus rather than a necessity, and nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds workflow meaning the schema does not convey, notably that if_match is 'needed to accept a proposal' and how edit/count behave. It reinforces rather than merely repeats the parameter docs.

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

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

States a specific verb and resource with clear scope: it 'changes one file of this organization's definitions, live for every member's agent at once.' An agent immediately understands this is a mutation tool. It does not name the sibling read_company_definitions, so the read/write routing is left implicit.

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?

Explains when each action applies (create from content, edit with find/replace, move via 'to', remove) and lays out the permission model, including who may write where and when if_match is required to accept a proposal. It never explicitly contrasts with read_company_definitions, so alternative selection is inferred rather than stated.

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