MoatDrop

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety and idempotency profile is covered structurally. The description adds that the resulting link is queryable via deep_extraction and that only URL-based links are created, which is useful context. It stops short of stating auth requirements, default enablement state, or behavior on duplicate/invalid URLs.

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 prose sentences up front, then a compact Args list — no filler or restated schema titles. The opening sentence is slightly dense with the cross-reference to deep_extraction, 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?

An output schema exists, so return-value documentation is not required. For a five-parameter mutation tool the description covers scope, channel limitation, and the non-obvious parameter formats. Remaining gaps — auth requirements, default enabled state, duplicate-URL behavior — are real but modest against what annotations and the output schema already supply.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden and does it reasonably well: expire_date is documented with ISO 8601 format and a concrete example, and the allow/block lists are documented as comma-separated IPs/CIDRs. name and original_url get only terse glosses, and the interaction between allow and block lists (if both are supplied) is unaddressed.

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 — creating an extraction-query link — and names the target consumer (deep_extraction). It also clarifies the creation channel (URL-based only), which implicitly separates it from the file-upload path. Sibling differentiation within the tool set is only implicit, since it never contrasts with update_link/delete_link/get_link directly.

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 bounds usage: 'creates URL-based links only' and routes the file case to the web UI or HTTP API. That is a clear when-not statement with an alternative path. It does not, however, cover prerequisites such as whether the URL must be publicly reachable or what happens if the link already exists.

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 only flag readOnlyHint=false, openWorldHint=true and idempotentHint=false; the description goes well beyond them by disclosing quota metering against the link owner's monthly limit, the credential types accepted, and a prompt-injection contract for handling the answer as untrusted data in <document_answer> tags. That is exactly the kind of 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?

Content is segmented into purpose, metering, safety, auth and args blocks with zero filler sentences; each paragraph carries load-bearing information. It is a little long for two parameters, but the security and credential paragraphs justify their length.

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 present the description needn't explain return values, and it still usefully describes how to treat the returned answer. Purpose, auth options, quota behavior, parameter conditionalities and safety handling are all covered, so an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: 'question: max 4000 chars' and moat_link as the bare hash (not a full URL), optional for mds_/share-derived mdo_ credentials and required for mdp_/account tokens. This conditional-requirement detail is richer than any schema structure 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?

The first sentence gives a specific verb+resource: 'Ask a question, get an AI-synthesized answer from a shared file.' That is unambiguous and distinct from sibling tools like extract_fields or get_link. It never names an alternative explicitly, so sibling differentiation is implied rather than stated, keeping it at a 4.

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 establishes the clear context of use (questioning a document uploaded by the link owner) and supplies the credential-dependent conditions for supplying moat_link, which tells an agent whether it can call the tool with its current auth. It gives no when-not-to-use guidance and does not point to extract_fields for structured extraction, so it falls short of a 5.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, so the safety profile is already covered. The description adds non-annotation context: the deletion is permanent and gated behind confirm=true, which is a real behavioral detail an agent must act on. It stops short of describing downstream effects (analytics history, auth requirements).

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, zero filler, with the permanence warning and the confirm gate front-loaded where an agent will see them.

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 explained, and annotations cover destructiveness and idempotency. What remains is minor: no statement about auth requirements or whether the deletion cascades to related analytics data.

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

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

Schema description coverage is 0%, so the description must carry the parameters. It fully explains the non-obvious one — confirm must be set to true for deletion to occur — going well beyond the schema's bare boolean "Confirm". link_id is self-evident and left implicit.

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 ("Permanently delete a link"), and the adverb "permanently" implicitly separates it from sibling disable_link/enable_link. It does not explicitly name the reversible alternative, so it stops short of full sibling differentiation.

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: call this when a link should be removed for good, and the description tells the agent the confirm=true prerequisite. There is no explicit when-not guidance (e.g. "use disable_link if you only want to stop redirects") despite disable_link/enable_link being direct 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description usefully adds that access is cut off but omits whether the action is reversible (enable_link exists) and what happens to an already-disabled link.

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 short sentence, front-loaded with the verb and effect and free of filler. It is efficient, though notably terse given the gaps identified elsewhere.

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 explained, and annotations cover the safety profile. Still, for a destructive mutation tool it should clarify reversibility and how it differs from delete_link, which are meaningful gaps for correct selection.

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

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

Schema description coverage is 0%, so the description must carry the burden of explaining link_id, and it says nothing about the parameter. The name is fairly self-evident, but the description adds no meaning beyond it.

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?

Specific verb (revoke/disable) plus resource (link) with the stated effect 'preventing further access', so the agent knows what happens. However, it never differentiates itself from the closely related siblings enable_link and delete_link, so the boundary is left to inference.

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

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

There is no guidance on when to disable a link versus deleting it or leaving it enabled, and no mention that enable_link reverses this operation. Usage is only implied by the verb, not stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the agent knows this is a safe, repeatable state toggle. The description adds the precondition that the link must be revoked or disabled, but says nothing about auth requirements, reversibility, or behavior when the link is already enabled.

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 short sentence with the action front-loaded and zero filler. It is efficient, though the extreme brevity leaves gaps that other dimensions penalize.

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 described, and the tool is a simple single-parameter toggle. Still, the description omits precondition edge cases (already-enabled link), any mention of permissions, and any parameter detail, leaving it minimally adequate.

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

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

Schema description coverage is 0% and the single parameter link_id has no title-level explanation in the schema. The description provides no additional meaning for the parameter, leaving the agent to infer its format and origin entirely from the name.

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 (re-enable) and resource (a revoked or disabled link), which clearly distinguishes it from the sibling disable_link and delete_link. It does not name those siblings explicitly, so it falls short of a 5.

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

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

The phrase 'revoked or disabled link' implies the precondition under which this tool applies, which is a usable usage cue. However, no alternative is named (e.g. disable_link as its inverse) and no when-not guidance is given, so usage is only 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?

Goes well beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true) by disclosing the quota/metering model, the PII-scrubbing and [REDACTED:<type>] output behavior, the null-means-unstated convention, and the prompt-injection warning that values are untrusted data to be reported inside <document_answer> tags. This is exactly the kind of safety and cost context annotations cannot express.

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

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

The purpose and the 'Not read-only' caveat are front-loaded, and the Args block is well organized. It is long, but nearly every sentence conveys non-obvious constraint or safety information rather than padding, so the length is largely earned.

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 structure need not be described, yet the description still clarifies the two ambiguous output cases (redacted strings and null). Combined with auth, quota, and input-format coverage, an agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: it enumerates supported JSON Schema keywords, the 100-field/4-level depth limits, the noun-phrase-not-question requirement that triggers a 422, and the precise credential-dependent optionality of moat_link. This is far more than the bare 'object' and 'string|null' types in the schema.

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

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

States a specific verb and resource ('Extract structured fields from a shared file as JSON matching schema') and immediately situates itself relative to a sibling by noting it is 'metered exactly like deep_extraction'. An agent can distinguish this from deep_extraction and the link-management siblings without opening any schema.

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

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

Gives concrete operating conditions: which credentials unlock the tool, when moat_link is optional vs required, and the document-size boundary ('text documents under ~120k tokens only'). It does not explicitly state when to prefer this over deep_extraction, only that the metering matches, so routing guidance is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, local read. The description adds little beyond that, mostly restating the payload, though it does hint at the three content areas returned. No auth requirements, rate limits, or freshness caveats are 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?

A single front-loaded sentence with no filler; every clause maps to actual returned content and 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?

An output schema exists, so the description need not enumerate return fields, and annotations cover the safety profile. A no-parameter read tool is well covered by one sentence, though a note on freshness or scope of the 'monthly' figures would fully round it out.

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, which per the rubric sets a baseline of 4; there is nothing parameter-related for the description to clarify. Schema coverage is also 100% for the empty object, so no compensation 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 a specific resource ('account') and enumerates the returned content (details, plan tier, monthly query usage), so an agent can tell it is the account-introspection tool rather than any of the link-oriented siblings. The verb is only implicit via the name 'get' rather than stated in the description, keeping it just short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use text, so usage must be inferred from the name and the fact that it takes no parameters. Because it occupies a unique domain (account state) among otherwise link-focused siblings, the implied usage is unambiguous, which fits the 'implied usage' level.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe read-only nature is covered. The description adds the aggregation semantics (totals and top-N rather than raw events), which is useful, but discloses nothing about scope, time range, or rate limits.

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 that names the resource and enumerates the returned aggregates with zero padding. Efficient and easy to scan, though quite sparse.

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-value detail is not required, and annotations cover the safety profile. What remains missing is any statement of scope/time range and any routing versus get_link_analytics, which is significant given the overlapping siblings.

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 single required link_id parameter is undocumented in both the schema and the description. 'For a link' only weakly implies what link_id is, so the description fails to compensate for the coverage gap.

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

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

States a specific resource and output shape ('Aggregate summary for a link: total queries, unique IPs, and top referrers'), which is clear and unambiguous. However, it does not distinguish itself from the sibling get_link_analytics, leaving the agent to guess how the two analytics tools differ.

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 when-to-use guidance, prerequisites, or routing to alternatives is provided. The presence of get_link_analytics (and get_link) among siblings makes the absence of any differentiation particularly costly, since an agent cannot tell which analytics tool to pick.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on permissions, error behavior for missing/invalid IDs, or what "full details" encompasses versus the analytics sibling.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity borders on under-specification rather than true conciseness.

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 explained, and the read-only annotations cover safety for this simple one-parameter fetch. What remains missing is usage routing and parameter meaning, leaving the definition only minimally adequate.

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

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

Schema description coverage is 0%: link_id is typed as integer but carries no description. The description's "a specific link" only vaguely implies the parameter's role and gives no format, source, or validity guidance to compensate for the schema gap.

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

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

"Get full details of a specific link" states a clear verb (get) and resource (link), and "full details" hints at a single-record fetch versus a listing. However, it never distinguishes itself from siblings like get_link_analytics or list_links, so an agent must infer the difference from names 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?

There is no explicit when-to-use guidance, no prerequisite (e.g. needing a link_id from list_links), and no mention of alternatives such as get_link_analytics. The phrase "a specific link" only weakly implies retrieval-by-identifier.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that — result ordering ('most recent first') and a hard result cap ('capped at 50') — but is silent on pagination, auth requirements, and whether the cap can be raised.

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; the parenthetical efficiently carries the two behavioral facts an agent needs. Nothing to trim and nothing buried.

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 present, return-value explanation is not required, yet the description still usefully states ordering and the 50-record cap. For a simple one-parameter read tool this is nearly sufficient; only the link_id semantics and pagination behavior remain unaddressed.

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 link_id has 0% schema description coverage, so the description carries the full burden. It only indirectly implies the parameter via 'for a link' and gives no type, format, or where-to-find-it guidance, which is thin for a fully undocumented 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 states the concrete resource and its content ('Raw access logs for a link'), and the 'raw' framing implicitly distinguishes it from the sibling get_analytics_summary. It stops short of naming that sibling explicitly, so an agent must infer the contrast rather than being told it.

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 statement of when to use this tool versus get_analytics_summary or get_link. The description only characterizes the output, leaving the selection decision entirely to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that results are scoped to the current user's secure links, but says nothing about pagination, result limits, or ordering.

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 short sentence with the scope constraint front-loaded and zero filler. Every word 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?

An output schema exists, so return values need not be described, and the input is trivial. However, for a 'list all' tool the absence of any note on pagination or result volume is a meaningful gap for an agent deciding how to consume the response.

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 no parameters, so there is no parameter semantics to document; baseline 4 applies. Schema coverage is 100% and nothing is left ambiguous on the input side.

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 (list) and resource (secure links) with a clear scope (for the current user). It does not distinguish itself from sibling get_link or explain how it differs from a filtered listing, but the core purpose is unambiguous.

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

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

The description gives no explicit when-to-use guidance and never names alternatives such as get_link for fetching a single link. The only usable signal is the scope phrase 'for the current user', which is implied rather than stated as a selection rule.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds one genuinely useful trait beyond the annotations, the PATCH-style partial update ("Only fields you pass are changed"), but it never explains what makes the operation destructive or whether authentication or specific permissions are required.

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, the core action front-loaded and the important partial-update caveat immediately following. Nothing is padded or redundant.

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

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

An output schema exists, so return values need not be described, but for a destructive mutation with 0% parameter coverage the definition is under-specified. It omits parameter meaning, permission requirements, and what destructive behavior (e.g., expire_date effects) the caller should 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 description coverage is 0%, so the burden falls entirely on the description, which never names name, link_id, or expire_date, nor explains formats such as expire_date syntax. The generic "fields you pass" phrasing communicates partial-update semantics but leaves all three parameters semantically undocumented.

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

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

The description names a specific verb (update) and resource (a link's properties), which is clearer than the sibling get_link/list_links. However, it does not distinguish itself from enable_link or disable_link, which also mutate a link's state, leaving the agent to infer the boundary from schemas 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?

There is no statement of when to use this tool versus enable_link, disable_link, delete_link, or create_link, nor any prerequisite or precondition. The partial-update sentence describes behavior, not the conditions under which the tool should be selected.

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