ArtifactSend

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

The description adds important behavior beyond the annotations: the sender sees each question and confidentiality follows the sender's rules. It still does not fully clarify whether the tool returns answer content, creates a question record, or notifies the sender synchronously.

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 definition is compact and front-loads the core concept, with the sender-visibility note immediately after. The first sentence is slightly oblique, but no sentence is wasted.

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

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

For a non-read-only tool with no output schema, the description partially explains return content (parts answering the question) and discloses sender visibility. It remains incomplete about what exactly is created or returned and how the optional document parameter affects behavior.

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 moderate at 67%, and the description adds some meaning by specifying one question in the user's words. However, it does not explain the undocumented question field's format or clarify the optional document parameter beyond what the schema already says.

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 identifies the resource (a shared document) and the one-question scope, but it describes the result rather than the action. It does not clearly state that the tool submits a question to the document owner, so an agent may confuse it with read_shared or list_questions.

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

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

There is no explicit guidance on when to use this tool instead of siblings such as read_shared, list_questions, or message_shared_sender. The one-question scope implies usage but does not establish selection criteria or exclusions.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the agent knows this is a destructive write. The description adds nothing beyond that: it does not say whether the deletion is permanent, whether sent digests or history survive, or whether confirmation/auth is required. For a destructive tool, that is a meaningful 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?

A single short sentence, front-loaded and free of waste, but its brevity comes from under-specification rather than discipline.

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

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

With no output schema, a destructive annotation, and an undocumented id parameter, the description should explain the effect of stopping (permanent? reversible?), the id's meaning, and how to locate it via list_schedules. None of that is present, so it is incomplete for a destructive mutation.

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?

One required parameter with 0% schema description coverage; the description never clarifies that 'id' is the schedule identifier (as opposed to a digest id or artifact id) nor its format. The description does not 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?

The sentence 'Stop a scheduled digest' is essentially the title restated with a verb ('stop') and the resource ('scheduled digest'). It does convey the action, but adds no scope, no distinction from siblings like schedule_digest or list_schedules, and is one step above a tautology.

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

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

No guidance on when to use this versus schedule_digest (pause/resume vs. cancel?) or list_schedules to find the id. No prerequisites, no mention of what happens to already-sent digests.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds workflow context beyond that – this is a fetch of the *current* state intended to be followed by an update – though it doesn't warn about stale snapshots or concurrent edits.

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; the return content comes first and the sibling hand-off second. 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?

No output schema exists, and the description does name the two things returned (HTML and file paths), which is the essential shape. It stops short of describing the return container or ordering, a minor gap for a one-parameter read 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?

There is one parameter with 100% schema description coverage ('its URL, slug, id or title'), and the description adds nothing about accepted identifier forms. With the schema doing all the work, 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 precisely what is returned: the current HTML of a link plus the paths of its files. It also contrasts itself with update_artifact, so an agent can distinguish the read side from the write side of the pair 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?

'for editing; update_artifact sends the new version' names the complementary tool and the workflow that selects it. It gives no explicit exclusions (e.g., when to use open_link instead), so it falls short of a full when/when-not statement.

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

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

The description adds real behavioral context beyond the annotations: each recipient gets an individual link, access 'door' and reading report, while the underlying content stays shared and updates together. That explains the isolation and sync semantics of the operation. It does not cover permissions, rate limits, or what the caller receives back, keeping it from a 5.

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 tight sentences with the core purpose front-loaded and no filler. The term 'door' is unexplained jargon that slightly muddies otherwise clean phrasing.

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 creation tool with no output schema, the description covers enough: what is created, who it is for, and how content stays shared. It does not say what the return value contains (e.g., the new link URL) or how the per-person link relates to link_report and list_links, leaving a small gap.

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

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

Schema coverage is 100%, so all four parameters — including email and only_them — are already documented in the schema. The description only echoes the 'name' idea and adds no format or interaction details beyond the structured fields, so baseline 3 applies.

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

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

The description states a specific verb and resource — making another link to the same artifact for one person — and the 'another' wording implies a variant of an existing link. It does not explicitly name or contrast with siblings like link_report or update_link, so it falls 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?

"Use one per investor or client" gives a clear context for when to reach for this tool (individual, named recipients). It stops short of naming alternatives or when-not-to-use cases, such as when a single shared link or a group link would be preferred.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully discloses what the response contains (readers, section time, clicks, rage clicks, views per day), but says nothing about permissions, data freshness, or whether the report is time-bounded.

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 front-loaded sentence with the resource and scope first, followed by a dense field list. Nothing is redundant, though the trailing enumeration is a comma-run that could be grouped more legibly.

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

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

With no output schema, the field enumeration is the only signal about return shape, and it covers the major metrics well. The remaining gap is that aggregation semantics and any time-range limits on the report are unstated.

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

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

Only one parameter and the schema documents it fully (URL, slug, id, or title), so the schema does the heavy lifting. The description reinforces the single-link scope but adds no new constraint on the identifier form or resolution behavior when a title is ambiguous.

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 scope: a full reading report for exactly one link, with the fields it contains enumerated. It doesn't name or contrast with the closest siblings (reader_activity, website_visits, room_report), so the agent must infer whether per-link vs aggregate is the differentiator.

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 'for one link' implies when this tool applies (per-link analytics) but there is no explicit when-to-use, when-not, or named alternative. An agent comparing link_report to reader_activity or website_visits gets no routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are ordered oldest first, threads include replies, and resolution state is returned. No mention of result limits or pagination, which is the only notable omission.

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 tight sentences: the first front-loads what is returned, the second front-loads ordering. Nothing is redundant or padding.

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?

There is no output schema, but the description compensates by describing the return contents and sort order for a simple zero-required-parameter read tool. Only pagination/result-cap behavior is left unstated.

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 both parameters are already documented, including the default of the 10 most recently opened links. The description's '(or all links)' merely restates that default without adding syntax, limits, or edge-case behavior — baseline 3.

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 (reader comments pinned on a link) and enumerates its payload — pinned text, replies, resolution state — so an agent knows exactly what it gets back. It does not differentiate from neighbors like reader_activity or list_questions, which keeps it below 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?

Usage is only implied: passing a link scopes to one link, omitting it covers all links, and open_only filters unresolved threads. There is no explicit statement of when to choose this over reader_activity or list_questions, leaving the agent to infer the boundary.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description contributes ordering ('newest first') and the returned fields, but says nothing about pagination or what happens when results exceed the limit, which matters for a list 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?

Very short and front-loaded: the resource scope and returned fields come first, ordering last. The telegraphic fragment style is dense rather than wasteful, though a full clause would read slightly cleaner.

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

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

With no output schema, the description must convey return values, and it does partially (views, readers, last-opened, sort order). However, for a list tool with a limit parameter, the absence of any paging/default-size behavior leaves a real gap.

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

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

Schema coverage is only 50%: 'query' is documented in the schema, but 'limit' has no description anywhere. The description never mentions limiting or paging, so it fails to compensate for the undocumented 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 names the resource ('My links') and, more usefully, what each entry contains (views, readers, last-opened time) plus ordering ('Newest first'), so an agent knows exactly what comes back. It is clear but does not distinguish itself from neighbors like link_report, recent_activity, or shared_with_me.

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?

'My links' implicitly signals an ownership scope, which is a mild differentiation from shared_with_me, but there is no explicit when-to-use, when-not-to-use, or named alternative. The agent must infer selection criteria from the resource name alone.

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

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

Annotations already cover read-only, non-destructive, closed-world, so the description's job is to add the rest — and it does, disclosing sort order ('Newest first') and that answers are included with each question. It stops short of describing pagination or what the default result set size is.

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

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

A single tightly packed sentence that front-loads the resource, then scope, then ordering. Nothing redundant and nothing padded.

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 read tool with annotations carrying the safety profile and no output schema, the description is nearly sufficient — but the undefined 'limit' behavior (default count, max) remains an open question an agent would need answered before calling it reliably.

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 50%: 'link' is documented (optional, omit for all links) and the description reinforces that with '(or all links).' The 'limit' parameter carries no description in the schema and no explanation in the description — no default, no maximum — so the coverage gap is only half compensated.

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 resource ('questions readers asked a link') and what comes with it ('the answers they got'), plus the ordering. It is clear what the tool returns, but it never names why it differs from close siblings like list_comments or reader_activity, so sibling differentiation 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?

Usage is only implied: 'a link (or all links)' hints at the via-link context, and the schema note says 'Leave out for all links.' There is no explicit when-to-use guidance and no pointer to list_comments or reader_activity as alternatives for adjacent data.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. Beyond that, the description contributes only the "My" ownership scoping and says nothing about result shape, ordering, counts, or what a digest record contains.

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 words with no waste, but this is under-specification rather than disciplined concision — there is no front-loaded statement of the action. A single additional clause ("lists the digests you've scheduled, newest first") would have cost little and added much.

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 tool with no output schema and no return-value documentation, the description must at least say what comes back; it does not. Given ~23 siblings and no output schema, an agent cannot tell what fields or how many results to 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The empty schema and the description agree that no filtering or paging inputs are accepted.

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?

"My scheduled digests." is a noun phrase that essentially restates the title "List digests" and the name list_schedules without supplying a verb or explaining what listing produces. The only added signal is the possessive "My", which narrows scope to the caller's own digests rather than all digests.

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

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

There is no when-to-use guidance and no mention of related siblings such as schedule_digest (creation) or delete_schedule (removal), so an agent gets no routing help. The possessive implies "only your own items", but that is inferred, not stated as usage guidance.

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

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

Annotations already declare this is a non-read-only, open-world, non-destructive operation. The description adds that it returns the room link and groups multiple links, but it does not disclose default access behavior, idempotency, permissions, or what happens to the included links; the 'folders' claim is also unsupported by the schema.

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 and front-loads the core action. The metaphorical 'one link and one door' phrase and the unsupported 'with folders' detail slightly reduce precision but do not bloat the text.

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?

There is no output schema, so stating that it returns the room link is useful. However, for an open-world creation tool with five parameters and no annotations covering creation semantics, the description does not explain access defaults, NDA implications, or folder behavior, leaving meaningful gaps.

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

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

Schema description coverage is 80%, so the schema already documents the access modes, NDA text, watermarking, and link formats. The description adds little parameter-specific meaning beyond referencing 'my links' and the return value; 'folders' does not map to any 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 names a specific verb and resource: putting several links into one data room and returning the room link. It is distinguishable from siblings like list_links or open_link, though the metaphor "one link and one door" and the mention of folders (not present in the schema) add some 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?

There is no guidance on when to use this tool versus alternatives such as link_for_person, send_artifact, or update_link. It also omits prerequisites, constraints, or when not to create a data room.

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, openWorldHint=true and destructiveHint=false, so the external-send nature is partly covered. The description adds real value by stating the message is emailed with the user's address as reply-to and that the message should be short, but it omits whether the sender sees the user's address, whether sending is reversible, and any rate or length 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 with no filler; the actor, action, recipient, and reply-address behavior all land immediately.

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 action with no output schema and annotations covering the safety profile, this is close to complete. Minor gaps remain around failure modes (invalid or expired link) and what the call returns, but nothing essential to invoking it 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 50%: the 'link' parameter is well documented with example formats, while 'message' has no schema description. The description partially compensates by framing it as the user's own short message, but adds nothing about length limits or formatting.

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 (emails) and clearly identifies both the resource (the user's short message) and the recipient (the person who shared a link), plus the reply-address behavior. It is distinguishable from siblings like send_artifact or ask_shared, though it never names an alternative 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?

Usage is only implied: the tool applies when replying to whoever shared an ArtifactSend link. There is no explicit statement of when to choose this over ask_shared, list_comments, or link_for_person, and no prerequisites or exclusions are given.

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 by disclosing a side effect ('The sender sees that it was opened'), which explains why readOnlyHint is false, and describes the conditional flow where a room with an agreement returns the agreement first. It also notes the write consequence of agree: true.

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

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

Three sentences that are front-loaded with the core action and waste little. The parenthetical URL examples mildly duplicate the schema's link description, which is the only 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?

No output schema exists, yet the description covers the return behavior for agreement-gated rooms, the side effect visible to the sender, and the meaning of both parameters. Nothing an agent needs to call it correctly 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, and the description still adds meaning by tying agree to the agreement-return sequence ('agree: true records that the user accepted it'). It doesn't restate the link format details beyond the schema, keeping the gain modest.

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 ('Opens') and resource ('document or data room shared with the user') along with the link domain, which distinguishes it from siblings like read_shared or get_artifact. An agent can tell exactly what object this operates on without reading 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?

Clear context: use when the user has an artifactsend.com/d/... or /r/... link. It doesn't explicitly exclude or name sibling alternatives (read_shared, get_artifact), so it stops short of full when/when-not 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?

The annotations already establish that this is a read-only, non-destructive operation. The description adds useful behavioral detail about what is returned: when visits occurred, how long they lasted, the order of sections read, and clicks/copies. It does not mention pagination or privacy constraints, but it meaningfully supplements the annotations.

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

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

The description is a single efficient sentence with the scope front-loaded and no wasted language. Every listed item helps the agent understand what the tool returns.

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 two required parameters, read-only annotations, and no output schema, the description does a good job naming the returned fields. It remains silent on pagination or volume limits, which is a minor gap for a visit-history tool.

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

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

Schema description coverage is 100%, so both required parameters are fully documented by the schema itself. The description reinforces that the result is scoped to one reader and one link, but adds no parameter syntax or format details beyond what the schema already provides.

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

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

The description clearly specifies the resource and scope: every visit by one reader of a link, including timing, duration, reading order, clicks, and copies. It is more specific than the title alone, though it does not explicitly contrast itself with sibling tools such as recent_activity or website_visits.

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 scope implies when to use it—when you need activity for a specific reader on a specific link—but the description gives no explicit when-to-use guidance, exclusions, or alternatives such as recent_activity for broader activity.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed world), and the description adds real context on top: the return shape varies by how the sender shared (full text vs. outline when shared by questions only), plus a confidentiality constraint governed by the sender's rules. It omits failure behavior when access is not granted, which keeps it short of a 5.

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

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

It is a single compact sentence with no filler, but it is a fragmented clause that buries the action and reads awkwardly ("as its sender shares it with AI"). The most decision-relevant fact, the full-text vs. outline behavior, is present but not 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?

With only two parameters, full schema coverage, and no output schema, the description correctly carries the burden of explaining return values (full text or outline) and the confidentiality condition. What is missing is only edge-case behavior, such as what happens when the link is expired or access is denied.

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 both parameters (link, document) are already documented with examples and data-room semantics. The description adds no parameter-level meaning beyond what the schema states, so the baseline 3 applies.

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

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

The description names the resource (a shared document) and what it yields (full text, or outline), and hints at retrieval, but it is written as a noun phrase without a clear verb, so the action must be inferred from the title. It does distinguish itself from siblings by noting it applies "after open_link", which an agent can use to place it in a sequence.

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?

"After open_link" implies a prerequisite and ordering, which is genuine usage guidance. However, it never says when to prefer this over ask_shared, get_artifact, or list_questions, nor does it state what to do if the sender has not shared with AI.

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, non-destructive and closed-world, so the safety profile is covered. The description adds useful scope ('all my links') and the 24-hour default, but says nothing about result volume, ordering, or truncation for large link sets.

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 tight sentences: the scope and default come first, the usage cue second. No filler, no restatement of the title.

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

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

For a zero-required-param read tool with annotations covering safety, the description supplies scope, default, and a use case — enough to call it correctly. Return-shape expectations (whether it includes timestamps, reader identity, link names) remain unstated, though no output schema exists to fill that gap.

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

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

Schema coverage is 0% — the single 'hours' property has no description or type constraints — so the description carries the burden and does so by naming the parameter's meaning, its unit ('hours'), and its default of 24. It does not state bounds (e.g., maximum window) or whether fractional/non-integer values are honored.

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+resource: it returns who opened which links over a time window, with an explicit default of 24 hours. The scope phrase 'across all my links' implicitly separates it from per-reader or per-site siblings like reader_activity and website_visits, but no sibling is named 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?

Provides a concrete triggering question type ('what happened today'), which tells the agent when this is the right call. It stops short of naming alternatives or exclusions (e.g., when to prefer reader_activity for a single recipient), so it is clear context rather than full routing guidance.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is clear. The description adds useful content about what the report includes, but it does not describe output format, pagination, permissions, or other behavioral limits beyond the annotations.

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

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

The description is a single concise sentence that lists the report’s relevant contents without padding. It is appropriately sized, though it could be slightly more front-loaded with a verb like 'Generates a report showing...'.

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

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

For a simple read-only tool with one fully documented parameter, the description conveys enough about the report’s contents to support selection. However, it omits usage guidance relative to similar activity-reporting siblings and does not explain return structure, leaving some gaps.

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

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

Schema description coverage is 100%, and the single parameter 'room' is documented in the schema as a URL, slug, or name. The description does not add any further detail about the parameter, so the schema carries the weight here.

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

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

The description clearly identifies the report’s contents: who opened the data room, which documents were read and for how long, and who accepted the agreement. It is specific about the resource and information returned, but it does not differentiate this tool from siblings like reader_activity or recent_activity.

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

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

The description gives no guidance on when to use this tool versus alternatives such as reader_activity, link_report, or recent_activity. It implies it is a data room activity report but does not state selection criteria or exclusions.

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

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

Annotations already indicate this is a non-destructive mutation tool with open-world behavior. The description usefully adds that delivery is by email on a recurring schedule in Pacific time and can be limited to some links, but it does not clarify what happens if a schedule already exists, whether multiple schedules can be created, or what confirmation is returned.

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

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

The description is very short, front-loaded, and contains no filler. Every phrase adds relevant information about scheduling, email delivery, timezone, or optional link filtering.

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 non-destructive mutation tool with five parameters and no output schema, the description covers the core action and delivery mode. However, it omits operational context an agent may need, such as whether repeated calls create duplicates, how to inspect or remove schedules, or what the call returns.

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 documents several parameters, and the description adds meaning for the undocumented links parameter by saying it can limit the digest to some links. It also reinforces Pacific time, but it does not add much beyond the schema for cadence, hour, note, or weekday, leaving the moderate schema coverage gap only partly addressed.

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: schedule an emailed reading digest. It adds useful scope details such as Pacific time and optional link filtering, but does not explicitly distinguish this from sibling scheduling tools like list_schedules or delete_schedule.

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 explains what the tool does but gives no explicit guidance on when to use it versus alternatives such as list_schedules or delete_schedule. There are no prerequisites, exclusions, or duplicate-schedule caveats.

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 establish that this is a non-read-only, open-world, non-destructive operation. The description adds useful behavioral context: the shared link tracks who opened it, read depth, time per section, and questions asked; updating via `link` preserves the same URL with new content; and the call returns the link and its settings. It does not discuss permission requirements, rate limits, or detailed side effects beyond annotations.

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

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

The description is front-loaded with the core purpose and then adds only the distinctions needed for invocation. It is appropriately sized for a tool with 14 parameters, and every sentence contributes useful selection or behavior 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?

Given the high schema coverage, nested objects, and absence of an output schema, the description is largely complete for selecting and invoking the tool. It explains content source options, update behavior, and that a link plus settings are returned. It does not mention some access-related parameters, but those are well covered by the schema.

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 high at 86%, so the schema already documents most parameters. The description still adds meaningful guidance by explaining the content-source mapping for Claude artifacts (`html` vs `react`) and that `link` triggers an in-place update. It does not cover parameters such as `access`, `ai_reading`, `allow`, or `expires_in_days`, but the schema handles those.

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: share/send a document, deck, HTML page, or Claude artifact as a tracked link. It also distinguishes the update behavior from creating a new share by explaining that passing `link` updates an existing link in place. The purpose is clear 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?

It gives clear usage context by mapping content types to parameters (`html`, `react`, `document`, Markdown, URL) and explains when to pass `link` instead of creating a new link. However, it does not explicitly name competing siblings such as `update_link` or state when not to use 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context—newest-first ordering and inclusion of links—but does not mention pagination, result limits, or completeness of history.

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 efficient sentence with no wasted words. The key scoping details—source, ordering, and included links—are 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 zero-parameter read-only tool with annotations covering safety, the description is largely complete: it states what is returned and how it is ordered. A minor gap remains around pagination or whether the full history is returned.

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

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

The tool has zero parameters, so the baseline is 4. The schema is empty and the description does not need to compensate for parameter documentation.

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

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

The description clearly identifies the returned resources—documents and data rooms previously opened via ArtifactSend—and specifies ordering and inclusion of links. It lacks an explicit verb like 'list' and does not differentiate itself from similar siblings such as recent_activity or read_shared.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. It implies a history-listing purpose through 'opened before,' but does not name when-not-to-use cases or competing sibling tools.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true; the description adds meaningful context on top: readers see the new version immediately, the URL stays the same, and the payload must be a complete document rather than a fragment. It stops short of saying the prior version is unrecoverable.

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 core action is front-loaded and every sentence is relevant, but the claude.ai import sentence is overstuffed, cramming a trigger condition, an instruction and a feature list into one clause-heavy run. A split would make it 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?

With 7 parameters at 29% coverage, no output schema and a destructive annotation, the description should account for all inputs; it covers the content payloads well but says nothing about react or title, nor what the tool returns. Adequate, with clear gaps.

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

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

Schema coverage is only 29%, so the description carries real weight: it says to supply the complete new HTML (or Markdown, or a URL) and, for pages loading files by relative path, those files — mapping directly onto html/markdown/url/files. It leaves react and title unaddressed, but adds far more than the bare 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 first sentence gives a concrete verb+resource: push a new version to an existing link, same URL. It is distinguishable from send_artifact (creation) and get_artifact (read). However, it never contrasts itself with the similarly-named sibling update_link, so an agent must guess which updater handles metadata vs. content.

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?

Two usage contexts are spelled out: replacing content on an existing link, and importing a claude.ai-only link (the onClaudeOnly case) so it gains per-section time, replays and comments. The closing pointer to get_artifact establishes a read-then-update flow. No explicit exclusions or 'use update_link instead' routing is given.

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, openWorldHint=true and readOnlyHint=false, so the safety profile is carried structurally. The description adds only the 'turn it off' nuance via the disabled concept and says nothing about reversibility, permission prerequisites, or what toggling disabled does to existing readers. Adequate but thin beyond annotations.

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

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

A single front-loaded sentence with zero filler that enumerates the changeable facets. Nothing 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 9-parameter destructive mutation with no output schema, the description covers breadth but omits reversibility, permission/auth requirements, and what happens to already-distributed links when settings change. The rich schema compensates for much of the parameter gap, but behavioral context is only minimally 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 coverage is 78% and the property descriptions are unusually rich (access enum meanings, ai_reading tradeoffs, allow examples, folder auto-creation), so the schema carries the semantics. The description adds no parameter-specific meaning beyond restating a subset of fields, which is the baseline 3 case.

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 ('Change') and resource ('a link') plus the concrete facets it controls: access, title, expiry, notifications, disabling. An agent immediately knows what domain the tool operates in. It does not, however, distinguish itself from siblings like update_artifact or delete_schedule.

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 by listing the mutable settings, but there is no explicit 'use this when…' or routing to alternatives such as link_for_person or delete-type siblings. The agent must infer selection from the tool name and the field list alone.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the bar is lower, yet the description still adds real context: the 10 MB ceiling, the fact that an existing file at that path is REPLACED, and that the link's page markup is not touched. It stops short of saying whether the old file is recoverable or what happens if two uploads race for the same path.

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 tight sentences with zero filler; the actor-scope ('one file ... by relative path') and the constraint ('Up to 10 MB') are both 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 3-param, no-output-schema, annotated write tool, the description covers what is uploaded, where it lands, size limits and non-effect on the page. The only material hole is content encoding for 'base64' and the lack of any mention of the result of a successful upload.

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 67% and the two documented params (link, path) already carry their examples in the schema; the description adds only the relative-path framing. The undocumented 'base64' param is left unexplained — no hint whether raw base64, a data URI, or a URL is expected, and the 10 MB limit is not tied to it explicitly.

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 (add/replace) plus resource (a single file served by a link at a relative path), with concrete file classes enumerated. It never names or contrasts a sibling such as update_link or send_artifact, so an agent must infer the boundary between 'edit the link' and 'upload an asset to the link' on its own.

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

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

The clause 'that a link loads by relative path, without changing the page' implies the scenario (attaching assets that the link's HTML references), but there is no explicit when-to-use versus update_link/send_artifact guidance and no prerequisites stated. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds scope (only outbound clicks from artifacts to your site, not all traffic) and the default lookback window, but says nothing about result size limits, ordering, or aggregation.

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 resource and the key scoping qualifier (clicked from your artifacts to your own website), with the time window trailing. 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?

A simple read-only tool with one optional parameter and no output schema; the description conveys what data comes back (visitors and pages) and the time window. Only the return shape's granularity and any limits remain unstated, which is minor here.

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

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

Schema coverage is 0%, so the description must carry the parameter — and it does, defining 'hours' as the lookback window with a stated default of 168. It stops short of giving an accepted range or units beyond hours.

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 (readers who clicked from artifacts to your own website) and the content returned (pages they visited). It is more concrete than siblings like reader_activity, though it never explicitly contrasts itself with those 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?

Use is implied — referral analytics — but there is no explicit when-to-use or when-not, and the very close siblings reader_activity and recent_activity are not mentioned as alternatives. The agent must infer the distinction.

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