SesApp Access Sheets

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

With no annotations, the description carries the burden well: it discloses Bearer auth requirement, a quota-exceeded path with PAYMENT-SIGNATURE and per-tier pricing (0.50/0.25 USDC), and a real security constraint (wifiPassword must never appear in Markdown and is only unlocked within a 150 m GPS geofence). It does not state what the call returns (no output schema), which is the remaining 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?

Front-loaded with the core action and the authoring format, then security, then payment/auth. The telegraphic style is dense but nearly every clause carries load. Minor redundancy where the wifiPassword warning is repeated in both the top-level description and the instructions parameter.

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 10-parameter mutation tool with no annotations and no output schema, the description covers the essentials an agent needs: payload format, required fields, security rules, auth, and the paid-retry path. It is only short of describing the created resource or its identifier, which an agent might reasonably expect.

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

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

Schema coverage is 80% so the baseline is 3, but the description adds genuine semantics the schema lacks: how wifiName/wifiPassword bind to the sesapp:wifi intent, how phoneNumber binds to sesapp:contact, the bilingual intent-label forms, and the fact that omitting the links while setting fields still appends WiFi/contact pages. That interaction logic is not recoverable from the schema alone.

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

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

States a concrete verb+resource ('Create an access sheet') and immediately defines what the primary payload is. It is distinguishable from get_fiche/update_fiche/delete_fiche by the 'create' verb, though it never names those siblings explicitly to draw the boundary.

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 is implied through the heavy formatting/authoring instructions, but there is no explicit when-to-use versus update_fiche, and no statement of when not to call it (e.g. reuse of an existing fiche). The agent must infer the create-vs-modify split from the name.

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

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

No annotations are present, so the description carries the burden of disclosing behavior. It does disclose the ownership constraint, the share-link cascade, and the Bearer auth requirement. However, it stops short of stating that deletion is permanent/irreversible or describing possible errors.

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 sentence, front-loaded with the action and object, with the important side effect and authentication included. There is no filler; every word communicates a meaningful constraint.

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

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

For a destructive, annotation-free tool with no output schema, the description covers the core action, ownership, share-link side effect, and auth. It is incomplete on usage alternatives and irreversibility/error behavior, but otherwise appropriate for a one-parameter delete operation.

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

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

Schema description coverage is 0%, and the description never explicitly names the id parameter, explains where to find it, or states its format. The only hint is the implicit inference that id identifies the owned access sheet, which is weak compensation for a low-coverage schema.

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

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

The description uses a specific verb ('Delete'), names the resource ('access sheet'), and adds a scope qualifier ('owned') plus the cascading effect on share links. This clearly distinguishes it from siblings like create_fiche, update_fiche, and revoke_share.

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

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

There is no explicit when-to-use guidance or mention of alternatives. While 'owned' and 'its share links' imply full-sheet deletion, the description does not say to use revoke_share for removing individual share links or list_fiches to locate the id.

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，描述必须承担行为披露的全部责任。它仅提及需要Bearer认证，但未说明删除是否永久、是否影响关联资源、是否幂等或错误响应行为。对于一个破坏性操作，这是显著的透明度缺口。

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?

描述非常简短，没有冗余句子，核心删除意图放在最前。但'Fleet/Platform'作为一个独立片段含义模糊，信息价值有限，稍有浪费。

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?

虽然工具参数简单，但无输出schema、无annotations，描述需提供更多上下文。它缺少删除的后果（如永久性、关联影响）、适用场景和可能的错误情况，仅凭当前信息agent难以全面评估调用影响。

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

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

Schema description coverage为0%，描述完全未提及id参数的含义、格式或用途，仅能依靠参数名'id'猜测。描述没有为参数增加任何超出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?

描述以明确的动词+资源开头（'Delete a webhook endpoint'），能够与兄弟工具如delete_fiche、update_webhook区分开。但'Fleet/Platform'这一片段含义不明确，可能让agent困惑其具体适用范围，略减清晰度。

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?

描述没有说明何时使用该工具而非替代方案（如update_webhook或revoke_share），也未提供任何使用上下文或排除条件。'Requires Bearer'仅提及认证要求，不属于使用时机指导。

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

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

No annotations are provided, so the description carries the burden. It discloses the Bearer auth requirement and the output shape, which is useful. However, it does not describe error behavior, rate limits, or what happens on an unmatched address, leaving some uncertainty for an agent.

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

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

A single, front-loaded sentence with no wasted words: action, output, purpose, and auth are all included. Every clause earns its place.

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

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

For a simple two-parameter tool with no output schema, the description covers the return value, use case, and authentication. It lacks explicit failure-mode handling or edge-case notes, but these are minor given the tool's simplicity.

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

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

Schema coverage is 100%: both 'query' and 'country' have descriptions in the input schema. The description adds 'postal address' to clarify the query's expected input and restates optionality, but it does not significantly extend the schema's meaning.

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?

Describes a specific operation ('Resolve a postal address') with explicit output ('formattedAddress + lat/lon') and a named consumer ('create_fiche'). The verb-resource combination clearly distinguishes it from sibling CRUD and webhook tools.

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

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

States the intended use ('for create_fiche (cover map and 150 m WiFi geofence)'), which tells an agent when to call this tool. No exclusions are needed because there is no sibling geocoding alternative, and the mention of Bearer auth provides a prerequisite.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It adds useful context: the sheet must be owned, Bearer authentication is required, and the response fields match list_fiches. However, it does not disclose error behavior such as 404 for missing sheets or 403 for unowned sheets, nor any id format expectations.

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

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

The description is a single front-loaded sentence: verb and resource come first, followed by the field-shape reference and authentication requirement. There is no filler, redundancy, or wasted words.

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

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

For a simple one-parameter getter with no output schema and no annotations, the description covers the key operational facts: ownership scope, Bearer auth, and return shape via list_fiches. It omits error-handling details, but for this level of complexity the information provided is largely complete.

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

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

Schema description coverage is 0%, and the schema only says 'id' is a required string. The description compensates by specifying that the id identifies an owned access sheet, which adds real meaning beyond the bare property name. For a single simple string parameter, this is sufficient.

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

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

The description states a specific verb ('Get'), a specific resource ('one owned access sheet'), and the lookup key ('by id'). It also references list_fiches, which distinguishes this single-record getter from its list sibling without ambiguity.

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

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

The description clearly conveys that this tool is for fetching a single owned access sheet by id, and 'Requires Bearer' gives necessary context for using it. It references list_fiches for field shape, implying when each sibling is relevant, though it does not explicitly spell out when to prefer list_fiches over get_fiche.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses the authentication requirement and the ownership scope, but it does not describe the return format, pagination, error cases, or what happens when the agent has no access sheets.

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

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

The description is two short sentences with no filler. It front-loads the core purpose and adds the authentication requirement immediately after, making it easy for an agent to parse quickly.

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

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

For a zero-parameter list operation, the description covers the essential facts: what is listed, whose sheets are listed, and the required authorization. It omits output shape and pagination details, but the low complexity of this tool keeps the gap minor.

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

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

The tool has zero parameters and schema description coverage is 100%, so the baseline is 4. The description adds no parameter-level detail, but none is needed since the input schema is empty.

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

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

The description uses a clear verb and resource: 'List access sheets' and adds a specific scope ('owned by the authenticated agent'). This distinguishes it from sibling tools like create_fiche, update_fiche, and delete_fiche without needing to inspect those definitions.

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

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

The description gives a concrete prerequisite ('Requires Authorization: Bearer') but provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions or conditions, so an agent must infer the appropriate use case from the tool name and siblings.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the operation is a read (list), the returned fields (token, url, expiresAt, viewCount, createdAt), and the auth requirement. It does not mention pagination, filtering, or error behavior, but for a simple list operation this is acceptable.

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

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

The description is a single, compact sentence that leads with the action and includes the key returned fields and auth requirement. Every word earns its place with no redundancy.

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

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

For a simple one-parameter list tool, the description covers the basic operation, returned fields, and auth. It is incomplete on parameter semantics and alternative-tool routing, but the absence of an output schema is partly mitigated by enumerating the return fields.

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

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

Schema description coverage is 0% and the description does not explicitly explain the 'id' parameter. 'For a fiche' implies id identifies the fiche, but this is indirect. The description adds little beyond what the raw schema shows, leaving the parameter meaning under-specified.

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

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

The description states a specific verb ('List') and resource ('guest links for a fiche'), and lists the returned fields. It clearly identifies the tool's function, though it does not explicitly contrast it with siblings like list_fiches or share_fiche.

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

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

The requirement for Bearer authentication gives a usage condition, and 'for a fiche' implies the tool is used to fetch shares per fiche. However, there is no explicit guidance on when to use this over alternatives such as share_fiche or revoke_share, leaving the selection 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?

With no annotations, the description carries the behavioral burden. It discloses a non-obvious output guarantee ('secret is never returned') and a required auth scheme ('Requires Bearer'), both useful to an agent. It does not describe pagination or explicit read-only semantics, but 'List' plus the secret guarantee provide adequate transparency for this simple read 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?

Three short clauses deliver the core action, a critical output guarantee, scope, and auth requirement without any filler. The most important verb-object pair is front-loaded.

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

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

For a parameterless list operation with no output schema, the description is largely complete: it states the operation, scope, auth, and a key response trait. It could add response shape or pagination details, but those are minor gaps given the tool's simplicity.

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

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

The input schema has zero parameters, so there is nothing for the description to add about parameter meaning; the baseline 4 applies. The 'secret is never returned' note is output-related, not a parameter concern.

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, 'List webhook endpoints', which unambiguously identifies the operation. It also adds scope ('Fleet/Platform') that helps distinguish it from sibling webhook tools like register_webhook, update_webhook, and delete_webhook.

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

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

The description makes the use case clear: call this tool to retrieve webhook endpoints, and it indicates the applicable scope ('Fleet/Platform') and an authentication prerequisite ('Requires Bearer'). It does not explicitly name alternatives or exclusion criteria, but the contrast with create/update/delete siblings is strongly implied.

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

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

With no annotations, the description carries the behavioral disclosure load, and it does so well: it reveals the HMAC SHA-256 signature format, that the secret is returned only once, and that at most 5 endpoints may exist. It stops short of describing failure behavior (e.g., when the 5-endpoint limit is exceeded) or whether registration triggers a verification request, but overall the side-effect profile is unusually transparent.

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?

Five short, information-dense sentences cover scope, resource, event vocabulary, signature mechanics, secret handling, capacity, and auth with no filler. The action is front-loaded and every clause earns its place.

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

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

Given no output schema, the description sensibly discloses the most important return behavior ('Secret returned once') and the endpoint capacity. It could add the response shape (e.g., endpoint id for later update/delete calls), but for a 2-parameter registration tool the provided context is sufficient for a competent agent to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents url and events. The description adds value by listing the valid event names (fiche.viewed, share.created, etc.) and clarifying the HTTPS requirement, which enriches the events parameter beyond the schema's generic 'Subset of events.'

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

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

Description opens with a specific verb and object: 'Register an HTTPS endpoint,' and enumerates the event types the endpoint can receive. This clearly distinguishes registering from sibling webhook tools like delete_webhook, list_webhooks, and update_webhook. The 'Fleet/Platform only' scope further narrows the purpose.

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

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

The description states a scoping condition ('Fleet/Platform only') and authentication requirement ('Requires Bearer'), and the event list tells the agent what subscriptions can be configured. It does not explicitly name sibling alternatives such as delete_webhook or update_webhook for lifecycle operations, but the verb and resource make the primary use case 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?

No annotations are provided, so the description carries the full burden of disclosing behavior. It states the destructive nature of the action ('Revoke'), the soft-revoke distinction via delayDays, and the Bearer authentication requirement. It does not mention error behavior or idempotence, but the key side effects are clearly disclosed.

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

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

The description is two short sentences that front-load the core purpose before adding the delay nuance and auth requirement. There is no wasted wording; every clause earns its place.

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

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

For a two-parameter mutation with no output schema and no annotations, the description covers the essentials: what is revoked, how to defer revocation, and what authentication is required. It does not state the return value or how to locate the token beforehand, but those are minor gaps for a straightforward revoke operation.

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

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

The schema leaves 'token' as a bare string, so the description adds meaning by calling it a 'guest share token.' For delayDays, it adds the valid range (1–365) and the 'soft revoke' concept beyond the schema's existing description. This compensates well for the 50% schema description 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 the exact action and object: 'Revoke a guest share token.' It is clearly distinct from the sibling tools, which create shares (share_fiche), list shares (list_shares), and delete other resources (delete_fiche, delete_webhook). An agent can tell when this tool applies without needing to infer from the name alone.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it give exclusions. The intended use is inferable from the phrase 'revoke a guest share token' and the sibling set, but there is no direct routing like 'use list_shares to find the token' or 'use delete_fiche to remove the entire fiche instead.'

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

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

With no annotations, the description carries the burden and does substantial work: it discloses the link is revocable, expiresAt is optional, the WiFi password is never embedded in Markdown but unlocked within 150 m of coordinates, and Bearer auth is required. It does not cover side effects on existing shares or error/return behavior, so it is not exhaustive.

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 each add distinct information: the core action, the optional parameter, the location-based behavior, and the auth requirement. The main action is front-loaded, and there is no filler.

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

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

For a low-complexity create tool, the description covers key operational details (auth, expiry, guest behavior), but it omits the role of the required id and the expected return. An agent would likely infer id from the tool name, but the missing id semantics keep it from being fully self-sufficient.

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 only 50%; expiresAt has a schema description but id has none. The description mentions 'Optional expiresAt (ISO)' but largely repeats the schema, and it never explains that the required id identifies the fiche to share. This is a meaningful gap for a required parameter.

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

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

The description opens with a specific verb and resource: 'Create a revocable guest link.' This clearly identifies the action and distinguishes it from sibling tools like list_shares and revoke_share, which handle listing and revocation rather than creation.

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

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

The action 'Create' implies usage when a new guest share is needed, and 'revocable' hints at pairing with revoke_share, but no explicit alternatives or when-not-to-use guidance is given. The proximity/location behavior offers context but not selection criteria.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose the authorization requirement and the specific fields returned, which is useful. However, it does not explicitly state that this is a read-only operation or describe error/edge-case behavior, though that is reasonably implied by 'status' and the listed data.

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

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

The description is very compact and front-loads the key returned fields before the auth requirement. Every phrase carries information. It loses a point for being a fragment rather than a complete, self-contained sentence, but there is no waste.

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

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

For a zero-parameter status tool with no output schema, the description provides the essential return fields and the auth requirement, which is sufficient for a basic call. It does not explain response formatting or possible failure states, but the low complexity keeps this from being a major gap.

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

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

The tool has zero parameters, so there is nothing for the description to elaborate beyond the schema. Per the baseline for 0-parameter tools, a score of 4 is appropriate since no parameter clarification is needed.

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 the specific resource (current agent plan) and enumerates the returned fields, so the tool's purpose is clear. It lacks an explicit verb such as "get" or "retrieve," and it does not explicitly distinguish itself from sibling tools, though its resource is distinct.

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

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

No guidance is given about when to use this tool versus alternatives. The only operational note is the Bearer authorization requirement, which is not usage guidance. Sibling tools are not mentioned or contrasted.

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

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

With zero annotations provided, the description carries the full disclosure burden, and it does substantial work: it reveals the payment prerequisite (PAYMENT-SIGNATURE via x402 v2), discloses the return value (Bearer JWT), and explains the price/quota consequence of each plan choice. It does not mention idempotency or double-charge risk for a money-moving operation, which would be valuable, but it goes well beyond a minimal statement.

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 dense sentences with zero filler. The core purpose is front-loaded, followed by the plan pricing table, then the authentication requirement, then the return type. Every clause earns its place and carries decision-relevant or call-relevant 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?

For a 1-optional-param tool with no output schema and no annotations, the description covers the essentials: purpose, plan options with cost implications, the required payment signature, and the Bearer JWT response. Minor gaps remain around renewal mechanics (extends vs. replaces an existing subscription) and failure behavior, but nothing that blocks a competent agent from invoking it correctly.

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

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

Schema coverage is 100% — the schema documents plan as an enum with 'SKU to purchase. Default agent.' The description adds real decision-making value beyond the schema by attaching price and quota semantics to each enum value (15 USDC/20 sheets, 79 USDC/200, 250 USDC/fair-use), which an agent needs to select the correct plan.

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

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

The description opens with the specific verb+resource pair 'Subscribe or renew,' which is a clear statement of the tool's function. The plan options and pricing further define the action, and the tool is immediately distinguishable from all siblings, which are fiche-management operations (create_fiche, delete_fiche, share_fiche, etc.).

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 tool is for purchasing or renewing a subscription, and the siblings are all fiche operations so there is no real overlap. However, the description never explicitly says 'use this when ...' or mentions exclusions such as when a renewal should be skipped or when a different sibling would be appropriate.

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

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

No annotations are provided, so the description carries the full burden. 'Requires Bearer' is a useful auth disclosure, but the description says nothing about what happens to omitted fields (overwrite vs merge), whether the update is destructive, error behavior, rate limits, or the 150 m geofence implications that are buried in the schema. For a mutation tool with zero annotation coverage, this is a significant 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 short clauses, front-loaded with the action and resource, no wasted words. However, the telegraphic style ('Same fields as create_fiche') leaves the reader to infer details rather than stating them, which trades clarity for brevity.

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

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

Given 11 parameters, no output schema, and no annotations, the description is thinner than ideal. It does hint at the sibling schema and the auth requirement, but omits mutation semantics, field-omission behavior, and any return information. Adequate as a minimum viable pointer, not complete for a mutation tool of this complexity.

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

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

Schema coverage is 73%, so most parameters have descriptions already. 'Same fields as create_fiche' adds a small pointer to the sibling's schema but no new parameter meaning. The 'typical: ... photos/links' note maps loosely to instructions, but the description adds little beyond the schema's already-rich instructions documentation.

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

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

States a specific verb and resource ('Update an owned access sheet') and distinguishes itself from create_fiche by referencing 'Same fields as create_fiche.' The ownership qualifier ('owned') also implicitly contrasts with share_fiche and get_fiche, though it doesn't explicitly route to alternatives.

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

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

Provides a narrow 'typical' use case (update instructions with photos/links) which hints at usage, but offers no explicit when-to-use/when-not guidance, no indication of when to prefer create_fiche vs update_fiche, and no prerequisites beyond a terse 'Requires Bearer' note.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It does state a Bearer token is required, which is useful, but it fails to explain whether the update is partial or full, whether existing fields are overwritten, what happens to events when omitted, or what response/error behavior to expect. For a mutating tool, this is a significant transparency 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?

The description is short and front-loads the core action, which is good, but the fragmented style ('Fleet/Platform. Requires Bearer.') reduces readability. It is concise without being elegantly structured, and several words are ambiguous rather than informative.

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

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

For a 4-parameter mutation tool with no output schema and no annotations, this definition is incomplete. It omits required parameter semantics, update semantics, error behavior, and any guidance for distinguishing among six webhook-related sibling tools. An agent cannot reliably invoke this tool correctly based on the description alone.

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

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

Schema description coverage is 0%, so the description must compensate, but it only repeats the property names 'url, events, or active' without explaining formats, allowed event values, or the role of the required 'id'. It adds no meaning beyond the raw schema and omits the only required parameter. This is insufficient for an agent to construct a correct request.

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

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

The description uses a specific verb and resource, 'Update url, events, or active', clearly indicating this tool modifies an existing webhook. It is distinguishable from sibling tools like register_webhook, list_webhooks, and delete_webhook, though it does not explicitly name them. The 'Fleet/Platform' phrase adds mild context but does not hurt overall clarity.

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

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

The description provides only a terse hint ('Fleet/Platform. Requires Bearer.') and no guidance about when to choose this tool over alternatives. It does not mention the required id, prerequisites beyond Bearer auth, or relationship to register_webhook/delete_webhook/list_webhooks. An agent is left to infer when this update path is appropriate.

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