lucid.page

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

Annotations already establish this is non-read-only, non-idempotent, and non-destructive. The description adds useful behavioral context beyond annotations: only documents you own can be bound, an lp_ API key is required, the result has a landing page and chapter navigation, and there is a 200-chapter limit. No contradictions with annotations.

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

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

The description is two tight sentences with no filler. The core action is front-loaded, followed by the key constraint and prerequisite. Every phrase earns its place.

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

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

Given the output schema, fully described parameters, and annotations, the description covers the important operational constraints: ownership, API key requirement, and chapter limit. It does not explain error behavior for unowned documents, but that is not essential for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaning beyond the schema by clarifying that documents must be owned and limiting bundles to 200 chapters, which directly refines the semantics of the items parameter. This extra context justifies a 4.

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

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

The description uses a specific verb and resource: 'Bind documents you own into a multi-chapter bundle.' It clearly distinguishes this from sibling tools, which all operate on individual docs rather than creating a bundle. The scoping to owned documents and multi-chapter bundles removes ambiguity.

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

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

The description gives clear context for when to use the tool — creating a bundle from documents you own — and states a prerequisite: requires an lp_ API key. There are no sibling tools for bundle operations, so explicit exclusions are unnecessary, though it does not spell out when not to use it.

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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context about authentication and access levels, which is not available in the annotations or 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?

Two compact sentences: the first states the core function, the second covers access constraints. No filler or redundant restatement of the tool name.

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 single-parameter read tool with an output schema and robust annotations, the description covers the essential operational details: what is fetched, which pages are accessible, and what credential is needed.

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 has 100% coverage for the single parameter, including a helpful description of what the slug is. The tool description adds no additional parameter information, so the baseline of 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 clear verb and resource: 'Fetch the canonical Markdown source of a page.' This unambiguously distinguishes get_doc from siblings like list_docs, update_doc, and delete_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 provides clear context about when access is permitted (public/unlisted vs. private) and the auth requirement for private pages. It does not explicitly name alternatives, but the access rules make the tool's role evident.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: ownership scoping, auth key requirement, newest-first ordering, and cursor-based pagination. 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?

Single sentence that packs in resource, scope, auth requirement, ordering, and pagination with no filler. Every phrase earns its place and the core action 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 read-only listing tool with a rich output schema, robust annotations, and fully documented optional parameters, the description covers all essential operational details an agent needs: auth, scope, ordering, and pagination.

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 explains both parameters. The description adds context about ordering and cursor pagination but does not introduce new parameter-level meaning beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb ('List'), resource ('documents and bundles'), scope ('owned by the authenticated account'), ordering ('newest first'), and pagination ('cursor'). This clearly distinguishes it from siblings like get_doc (single document), delete_doc (mutation), and create_bundle (creation).

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

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

The description makes clear this is the listing operation for the authenticated account's documents and bundles, and it notes the required lp_ API key context. It does not explicitly name alternatives or exclusions, but the listing scope is unambiguous and enough to route an agent correctly.

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?

Beyond the annotations, the description discloses the auth requirement, the fact that the URL stays the same, and that every update is retained as a revision. These are useful behavioral details that match the annotations, including the non-idempotent hint. It does not contradict any annotation.

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

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

The description is two sentences with no wasted words. The core action is front-loaded, and the important behavioral consequences (URL stability, revisions, auth) are stated efficiently.

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 output schema exists, the annotations cover safety semantics, and the input schema has 100% parameter documentation, the description provides the remaining context an agent needs: ownership, auth, URL behavior, and revision history. Nothing essential is missing for selecting or invoking the 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 the schema already fully documents slug, title, and markdown. The description adds only implicit alignment with the markdown parameter ('Replace the Markdown') and does not enrich parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Replace the Markdown of a page you own.' It clearly identifies this as an update operation on an existing published document, and the title reinforces the distinction. This differentiates it from sibling tools like publish_doc and delete_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 gives clear context: it applies to pages you own, requires an lp_ API key, and updates the existing URL rather than creating a new document. It does not explicitly name alternatives or state when not to use it, so it earns a 4 rather than a 5.

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