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 and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing that behavior changes with input (index vs. matching definitions vs. files), which is not evident from the schema alone. Pagination/change semantics are left implicit.

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

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

Three tight sentences, front-loaded with the resource description followed by the input-mode rules. The metrics enumeration (KPIs, revenue, players, churn...) is slightly listy but does convey scope and earns its 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?

An output schema exists, so return values need not be spelled out, and annotations carry the safety profile. The description covers content and input modes adequately; the remaining gap is the unstated relationship to the write counterpart and the meaning of a 'verified query'.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes further by tying the query and paths inputs to distinct result modes (matching definitions vs. files). The since and organization parameters receive no description-level explanation, so it is not fully complete.

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

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

States a specific verb+resource ("Returns this organization's own definitions of its metrics, terms and rules, and its verified queries") and enumerates the content types, so the agent knows exactly what it retrieves. It does not explicitly contrast with the write-side sibling write_company_definition, leaving that read/write distinction to be inferred.

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

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

Gives explicit mode-selection rules: "With no input, the index of every definition. With query, matching definitions. With paths, the files." This tells the agent how to pick behavior, but names no alternatives or when-not-to-use conditions relative to the sibling write_company_definition.

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 safety is covered, yet the description still adds real behavioral value: links are returned as ids and never URLs, and a person is keyed by invite address before sign-in and by account id after. That identity-keying detail materially affects how an agent uses the result.

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, front-loaded with the return contents and the usage trigger. Every sentence contributes something, though the aside about creating a new link is the least essential of the set.

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

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

For a single-parameter read tool with an output schema, annotations covering the safety profile, and full schema coverage, nothing an agent needs is missing. The description even preempts the identity-format question that the output schema alone would not resolve.

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 single parameter has 100% schema description coverage ("the app to read sharing for"), so the schema already carries the meaning. The description adds no syntax, format, or constraint detail about app_id beyond what the schema states, which is the expected baseline when coverage is complete.

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

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

States a specific verb and resource (reads an app's sharing state) and enumerates exactly what is returned: public/private flag, live share links as ids, and invited people under grants. That level of specificity makes it immediately distinguishable from set_access and revoke-grant.

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 who can open an app." It also routes around the write path indirectly ("Giving someone a link means making a new one") and names revoke-grant as the consumer of the returned identity form. It stops short of explicitly saying "use set_access to change sharing," so it is clear but not exhaustive.

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

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

Goes well beyond the readOnly/openWorld annotations: reserved apps return version 0 with no files, failed apps return the last live version plus a problem, large apps paginate into named parts, stored records are intentionally excluded, and it warns that republishing a past version's files puts a bad publish back. This is exactly the operational context annotations cannot carry.

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?

Purpose is front-loaded, but the body is an undifferentiated run-on of six dense sentences mixing payload description, edge cases, exclusion rules, publish semantics, and pagination hazards. Every fact is useful, yet a bulleted or paragraph-segmented structure would make it far more scannable.

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 six-parameter read with an output schema, this covers the remaining gaps: partial results, oversized apps, reserved/failed app states, what is deliberately omitted, and how the returned version relates to a subsequent publish. An agent has enough to call it correctly in every described state.

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 83%, but the description adds real meaning: paths are selected from the returned manifest, and version carries a non-obvious hazard (publishing old files against the live version reintroduces a bad publish). from_line/to_line handling of oversized lines is also clarified, though development_token is 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?

Opens with a specific verb and resource: 'Returns the complete currently published source of an existing app, by the app_id'. It enumerates the payload (authored files, live declared schema, compact context, editor checkpoint), distinguishing it clearly from list_apps, get_app_status, and checkpoint_app.

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 implied rather than stated: the version parameter guidance ('reads a past version instead of the live one') and paths guidance ('selected paths from the returned manifest') hint at when to filter or roll back, but no sibling tool is named and there is no explicit 'use get_app_status instead when...' 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 readOnly, non-destructive behavior, so the safety profile is covered. The description adds meaningful context beyond annotations: it discloses the exact status categories returned and states that no status remains pending after a publish, which informs polling behavior. It does not cover permissions or rate limits, but the output schema handles the return shape.

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

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

The description is two sentences, front-loaded with the return values followed by usage guidance. It is dense and mostly earns its place, though the em-dash construction in the second sentence is slightly awkward and could be split for easier parsing.

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

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

With an output schema and annotations present, the description covers the tool's purpose, status values, and when to use it versus publish. It omits error handling (e.g., invalid app_id) but is otherwise sufficient for an agent to call it correctly.

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

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

There is one parameter with 100% schema description coverage ('the app id to check'), so the schema fully documents it. The description does not add any semantic detail about the app_id beyond what the schema provides, which is acceptable given full coverage.

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

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

The description opens with a specific verb and resource ('Returns where an app stands') and enumerates the exact status values: created and never published, ready, or failed with the reason. This clearly differentiates it from the sibling 'publish' tool by noting that publish already returns the final status.

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

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

It explicitly states when to use the tool: 'when the person asks whether their app is up, or whether a reserved app ever got content.' It also names the alternative ('publish already returns the final status') and clarifies that nothing stays pending after publish, so the agent knows when not to call 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 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=true and destructiveHint=false, so safety is covered. The description adds useful context beyond that: a sign-in is required, and apps can share a name so app_id is the disambiguator. It does not address result size, pagination, or ordering for what is billed as an exhaustive list.

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?

Purpose and return fields are front-loaded, then usage, then caveats. It is tight overall, though the final two short sentences about organization read as clipped fragments and could be merged for smoother 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?

One optional parameter, an output schema that already defines the return shape, and annotations covering the safety profile — the description covers everything else an agent needs: auth requirement, default-scope behavior, and name-collision handling.

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 genuinely extends the organization parameter: omitting it lists the default organization, the personal one if present, and names any others, while supplying it lists that one instead. That scoping behavior is not in the schema text.

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 ("Lists every app you can reach") with the returned fields (URL and status). It also explains the app_id/duplicate-name relationship, which cleanly separates it from single-app siblings like get_app_context, get_app_status, or checkpoint_app.

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 two concrete triggers: the person asks what they have, or you need an app_id you don't already hold — the latter implicitly says not to call it when you already have an id. It never names a sibling alternative (e.g. get_app_context) explicitly, so routing between app tools is only inferable.

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 readOnly and non-destructive annotations, the description discloses the permission-dependent visibility semantics: shared collections return all records, private collections return only the caller's own, and assigned collections return only records assigned to the caller unless they edit the app. It also explains pagination behavior and states what is returned in each mode.

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

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

The description is dense but well-structured: it first states the overall read behavior, then explains records mode, pagination, collections mode, and field provenance. Every sentence carries useful operational meaning, with no filler.

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

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

Although an output schema exists, the description still usefully explains the shape of the two return modes and pagination termination. Combined with the annotations and complete parameter schema, an agent has enough context to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents app_id, cursor, and collection. The description reinforces the collection and cursor semantics but adds little parameter-level detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb-resource pair: it reads an app's data and lists either one page of a collection's records or the app's declared collections. The two operating modes are clear, though it does not explicitly name sibling alternatives such as get_app_context 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 clearly explains when to use each mode: pass a collection to list its records, omit it to get the app's collections, and pass cursor to continue pagination. It does not explicitly say when to prefer this tool over sibling tools, so it falls short of full alternative-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 declare destructiveHint=true, readOnly=false, idempotent=false, and the description corroborates with specifics an agent needs: a stale base is refused, a `find` miss refuses the publish, an unbased publish replaces every file, an editor's publish waits for owner approval at the Data address, personal-data detection is reported, and 'Files are live only when this call returns `ready`.' That is substantial context 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?

Front-loaded correctly: the create-vs-change contract leads, then edits, assets, work_context, data publications, and finally the `bundle_bytes`/`ready` verification cues. It is dense and topic-organised, but several sentences are elliptical to the point of ambiguity ('Files carry literal angle brackets.', 'A changed source, argument, selection, collection, or field is a new publication') and some material duplicates what `get_deploy_instructions` is said to return.

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 21-parameter, deeply nested tool with an output schema, this covers create, incremental update, edits, assets, skills, schema/storage, data publication, approval flow, and version recovery — enough to act correctly. Minor gaps remain: `contract_version` and `development_token` are never mentioned, and the relationship between `edits` and `files` in a single call is left implicit.

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 90% schema coverage the baseline would be 3, but the description adds real semantics the schema cannot: the provenance rule for `base_version`, the find-once-unless-`count` rule for `edits`, the two-call asset flow (declare sha256/bytes, then PUT bytes before republishing), what `data_publication` must never contain (rows), and the constraint that `work_context`/`summary` carry no credentials or stored records. That materially changes how an agent fills these fields.

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

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

Opens with a specific verb and resource pair — 'Create an app from its files, or change one' — and immediately distinguishes both modes by which parameters select them (omit `app_id` vs supply `app_id` + `base_version`). It also names the siblings it is not (`get_app_context`, `list_apps`, `checkpoint_app`, `get_deploy_instructions`), so an agent can route correctly without opening other 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?

Explicitly states when to create vs. change, when to use `edits` instead of whole files, when `base_version` is required and what happens without it, and where to go for the less common publishes ('`get_deploy_instructions` returns ... the less common publishes: rename, reserve an address ...'). It also routes the agent to `checkpoint_app` when work stops unpublished and to `get_app_context` with `version` for past versions — genuine when/when-not/alternative guidance throughout.

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 flag destructive/openWorld/non-idempotent, but the description adds the operationally critical detail the annotations cannot: links are non-idempotent (calling twice yields two live links), an already-stopped link reports 'not live' rather than failing, revocations persist even when the app is public or link-shared, email grants send mail while id/name grants do not, and email invites require a Cloche sign-in. That is exactly the beyond-annotation context an agent needs before calling a destructive tool.

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

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

Length is justified by 10 parameters and 8 access modes, and each claim largely earns its place, but it is delivered as one undifferentiated paragraph with notable repetition (revoke-link and its already-stopped case are explained twice). A structured breakdown by access mode would let an agent find the relevant clause far faster.

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 burden of a complex multi-mode mutation: permissions and role semantics, invite/org behavior, link lifecycle and expiry, revocation permanence, idempotency caveats for link creation and revocation, and where to source ids from get_access. With an output schema present, no return-value explanation is owed.

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 90% (baseline 3), yet the description still layers meaning: role 'user' is the ordinary invite vs editor's wider power, a link can never be editor, expires determines self-termination, organization_name is Owner-only and only with invite_to_organization, and name grants defer to stronger existing access. The only gap is it doesn't consolidate these into a parameter-by-parameter mapping.

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

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

Opens with a concrete verb+resource and scope: 'Changes who can reach an app.' The sibling set is answerable from this alone — get_access is the read counterpart the description repeatedly routes to, while this tool mutates sharing state. An agent can distinguish it from get_access, publish, or delete_app 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?

Explicit trigger context ('For when the person asks to share, invite, or take that back') plus a mode-by-mode account of when each access value applies, and repeated pointers to get_access for discovery (links, grants, link_id). It stops short of cleanly separating when to use this tool versus get_access or checkpoint_app in one place, but the guidance is strong and concrete.

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.