lucid.page

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, openWorld=true, so the safety profile is covered and the description is not required to repeat it. The description adds auth requirements and the ownership constraint, which annotations cannot express. It stops short of warning that repeated calls append duplicates (implied by non-idempotency) or describing error behavior.

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 dense sentence with the ownership/auth constraint front-loaded, then the parameter rule. No filler and nothing repeated from 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?

An output schema exists, so return values need not be explained. The description covers everything an agent needs to call it correctly: auth requirement, ownership precondition, and the mutually exclusive parameter rule.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a genuine cross-field constraint absent from the schema: 'exactly one of slug or url' is required, and it clarifies title applies to links only. That is real value beyond the per-field descriptions.

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

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

States a specific verb (Append) and resource (one item to a binder) with clear scope. It is easily distinguished from sibling create_binder (which makes the binder itself) and the doc-level tools, so an agent can route correctly 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?

Gives concrete preconditions: requires an lp_ API key, the binder must be one you own, and exactly one of slug or url must be passed. It does not name an alternative tool or state when-not to use it, so it falls short of the top score.

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 auth requirements (lp_ API key), hard quotas, the serving URL pattern, and the indexability rule for public binders. It could say more about failure modes (e.g. exceeding limits) or slug generation, but the behavioral picture is substantially richer than readOnlyHint/openWorldHint alone.

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 dense sentence that front-loads the core definition before layering quotas and indexability. Nearly every clause earns its place, though the URL/key/limit clauses could be split for easier scanning.

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 values need not be explained, and the description covers creation semantics, auth, quotas, visibility defaults, and indexing. The remaining gap is that slug behavior in the served URL is never explained as derived rather than supplied.

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

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

Schema description coverage is 100%, so the schema already documents title length, item structure, and the mutually exclusive slug/url fields. The description only restates that items are ordered and notes are optional, so it hovers at the baseline rather than adding new parameter syntax or constraints.

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 (create) and resource (binder), then defines the resource precisely: an ordered list of lucid.page pages and external links with optional notes. This clearly separates it from the sibling add_to_binder, which appends to an existing binder rather than creating one.

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 operational context: requires an lp_ API key, up to 100 binders per account, 500 items per binder, and what makes a binder indexable. It does not explicitly say when to choose this over add_to_binder, but the creation semantics make that inference safe.

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?

While destructiveHint=true already flags the destructive nature, the description adds valuable specifics: deletion is permanent, the URL stops serving immediately, and the document cannot be recovered. It also discloses the authentication requirement. No contradiction with annotations.

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

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

Two short sentences convey the action, ownership requirement, auth requirement, immediacy, and irreversibility. Every clause earns its place, and the most important information is front-loaded.

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

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

For a single-parameter destructive tool with full schema coverage and an output schema, the description covers everything an agent needs: what it does, who can use it, what happens, and the permanence. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents the slug parameter. The description adds no additional parameter-level semantics beyond the schema, which is the expected baseline.

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

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

The description uses a specific verb ('delete'), names the resource ('page/document'), and adds critical qualifiers ('permanently', 'you own'). It clearly distinguishes this from sibling tools like get_doc, update_doc, and publish_doc.

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

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

The description clearly states the precondition for use: the page must be owned and an lp_ API key is required. It does not explicitly enumerate alternatives or when not to use the tool, but the usage context is clear enough for an agent to select it appropriately.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond these: it clarifies the access model (public/unlisted open, private requires owner's lp_ API key) and specifies that it returns Markdown source. This goes beyond what annotations provide, so a 4 is warranted.

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 sentences with no wasteful phrases. The first sentence immediately states the core purpose, and the second covers access requirements. Information is front-loaded and every word contributes to understanding. This is an exemplary concise structure.

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

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

For a single-parameter read tool with an output schema and comprehensive annotations, the description covers all essential aspects: what it fetches, access conditions, and the API key requirement. The output format is handled by the output schema, and no extra clarifications (e.g., error handling) are needed for such a straightforward operation. It is fully 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?

The schema covers the only parameter (slug) with a clear description of its meaning. The tool description does not add additional parameter-specific information, but with 100% schema coverage, the baseline of 3 is appropriate. The description's mention of 'https://lucid.page/<slug>' aligns with the schema's URL explanation, offering no extra value.

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

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

The description states a specific verb ('Fetch') and a precise resource ('the canonical Markdown source of a page'). It clearly differentiates from siblings like list_docs (which lists documents) and mutation tools like update_doc or delete_doc. The phrase 'canonical Markdown source' leaves no ambiguity about what is returned.

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

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

The description provides clear context on when the tool is appropriate by outlining access rules (public/unlisted vs private, with owner's API key). It does not explicitly name alternatives or state when not to use it, but the read-only nature makes it unambiguous that this is the default retrieval tool for a single document. The lack of explicit exclusions is a minor gap.

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 read-only, idempotent, and non-destructive behavior, so the description does not need to repeat that. It adds useful behavioral context by specifying that the output differs based on whether an lp_ API key is present, which is not captured by 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, tightly worded sentence that front-loads the primary purpose and adds the conditional plan-status behavior without any redundant phrasing. 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?

With no parameters, a full output schema, and safety annotations, the description supplies the only missing context: what category of information the tool returns and how key presence changes the result. Nothing needed for correct invocation is omitted.

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

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

The tool has zero parameters and the schema coverage is trivially 100%, so there is no parameter documentation burden. The description reinforces that no input is required, which is adequate for a parameterless tool.

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 ('Show') and a specific resource ('lucid.page account matrix', 'plan status'), and clarifies the two display modes (anonymous vs lp_ API key). This clearly distinguishes it from the sibling document operations like get_doc or list_docs.

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 implies usage: call this tool to inspect account limits and plan status, especially before or after other operations. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions, so the guidance is only implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds value beyond them by disclosing the auth requirement (lp_ API key), the sort order (newest first), and the pagination model (cursor). Return shape is omitted, but an output schema exists, so that is acceptable.

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

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

A single front-loaded sentence carrying scope, auth, ordering, and pagination with no wasted words.

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

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

With annotations covering the safety profile, an output schema covering returns, and 100% parameter documentation, the remaining gaps an agent needs — auth, ordering, pagination — are all stated. Nothing essential is missing.

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

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

Schema description coverage is 100%, so limit and cursor are fully documented in the schema. The description only corroborates that pagination is cursor-based and adds no format detail beyond it, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (documents) with scope qualifiers: owned by the authenticated account, newest first. It does not explicitly differentiate from siblings like get_doc or search-style tools, but the scope constraints make its domain clear.

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 — list your own documents — but the description never says when to prefer this over get_doc or another discovery tool, nor any exclusions. Adequate but leaves routing 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?

The description adds substantial behavioral detail beyond the annotations: anonymous works without an account, anonymous publishes return a one-time claim_token, and the page can later be claimed or updated with an lp_ key. This discloses auth needs, ownership, and downstream actions, which is exactly the kind of context that helps an agent. No contradiction with 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 three sentences with no filler; the primary purpose and returned URL are front-loaded, followed by essential auth and claiming details. Every sentence contributes operational value.

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?

The description is complete for a publish action: it explains result URL, anonymous vs. authenticated behavior, ownership, claim token, claim link, and the agent-facing claim endpoint. Combined with a full input schema and output schema, nothing critical is missing.

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

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

Schema description coverage is 100%, so the parameters are already well documented in the schema. The description does not add new meaning for ttl, title, markdown, or visibility beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Publish Markdown as a beautifully typeset page and receive its https://lucid.page/<slug> URL.' This clearly states what the tool does and its output. It also differentiates from siblings by emphasizing creation/publishing rather than updating, deleting, listing, or getting docs.

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

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

The description provides clear usage context: it works anonymously, and with an lp_ API key the page is owned and can be updated later. It also explains the anonymous flow with a claim_token and claim link, which tells an agent what to do after publishing. It does not explicitly name alternatives like update_doc, but the context makes the appropriate paths clear.

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

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

Annotations only assert non-readOnly, non-idempotent, non-destructive. The description goes beyond by disclosing that every update creates a revision, the URL remains unchanged, a mismatch returns 409 with current_version, and an API key is required. These concrete behavioral traits give the agent a clear picture of effects and failure modes.

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

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

Three tightly written sentences with zero fluff. The first sentence states the essential action and prerequisite, the second covers side effects, and the third explains the conflict guard. Every sentence earns its place and the information is front-loaded.

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

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

Given that an output schema exists and annotations cover the safety profile, the description is comprehensive enough: it covers ownership, prerequisites, return-state behavior (conflict), and versioning. An agent can confidently call this tool with the provided schema plus these behavioral notes.

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 already has 100% parameter coverage, so baseline is 3. The description adds meaningful operational meaning to expected_version: how to obtain it (from get_doc) and what happens on conflict (409 with current_version). It also frames markdown as 'replace' rather than merely 'update', clarifying the overwrite semantics.

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 starts with a precise verb phrase 'Replace the Markdown of a page you own' and the resource (published document), making the tool's core function unmistakable. It also distinguishes from siblings by naming the ownership requirement and the update (rather than create/delete/publish) nature.

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

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

The description provides clear operational context: it explicitly states the authorization requirement (lp_ API key) and gives a concrete workflow for safe updates — read expected_version via get_doc and pass it to guard against overwrites. It does not explicitly name alternative tools for when not to use this one, but the context implies it is the update tool among the siblings.

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