lucid.page

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

Annotations only provide three boolean hints; the description adds concrete behavior: it creates a bundle with a landing page and ordered navigation, caps at 200 chapters, and requires ownership of the documents. This gives the agent useful operational context without contradicting 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?

Single sentence with no redundancy; the key action and constraints are front-loaded. It efficiently conveys the tool's purpose, prerequisite, and limit.

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 create tool with 4 documented parameters and an output schema, the description covers the essential operational constraints: ownership, API key requirement, chapter limit, and the resulting bundle structure. Minor gaps like error handling or idempotency are not needed given the annotations and output 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?

Input schema covers all 4 parameters with descriptions, so the baseline is 3. The description adds one extra constraint ('Up to 200 chapters') that relates to the items array, but otherwise does not elaborate on parameter syntax or formats beyond the schema.

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

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

The description opens with 'Bind documents you own into a multi-chapter bundle', clearly identifying a create operation for a composite resource. It distinguishes from sibling doc-level tools by specifying the bundle's own landing page and ordered chapter navigation, making it distinct from publish_doc, 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 states a clear prerequisite ('requires an lp_ API key') and a scope condition ('documents you own'), which tells an agent when it can use the tool. It does not explicitly name alternatives or exclusions, but the context is adequate for distinguishing from sibling single-doc 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 mark destructiveHint=true, but the description adds specific behavioral details: the URL stops serving immediately and cannot be recovered. This goes beyond the annotation by explaining the effect and irreversibility. 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?

One sentence that conveys all essential information without fluff. It is front-loaded with the primary action and includes critical caveats (ownership, key, permanence). 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?

For a destructive operation with a single parameter, the description is complete. It covers prerequisites, effect, and irreversibility. The presence of an output schema covers return details. No 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 covers 100% of the single parameter with a clear description of 'slug' as the path part of the URL. The tool description does not add extra semantics for the parameter beyond what the schema provides. 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 clearly states the tool's function: 'Permanently delete a page you own.' The verb 'delete' and resource 'page' are specific, and the title matches. It distinguishes from siblings like get_doc, update_doc, and publish_doc, which handle other operations.

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 states a prerequisite ('requires an lp_ API key') and a condition ('you own'), giving clear context for when to use. It doesn't explicitly say 'use this when you want to delete' but that is implied. It also mentions uniqueness (permanent, unrecoverable) which helps avoid misuse. No explicit alternative comparisons, but the deletion purpose is distinct.

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, idempotentHint, and destructiveHint, so the safety profile is established. The description adds valuable behavioral context about access restrictions and authentication requirements for private pages, going beyond the structured 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 sentences: the first states the core function, the second adds the only essential access caveat. No wasted words or redundant restating of the schema.

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 strong annotations and an output schema, the description covers the essential behavioral and access information. It does not need to explain return values because the output schema exists.

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 only parameter, slug, is fully documented in the input schema with a clear explanation tying it to the URL path. The description adds no additional parameter-level meaning, so with 100% schema coverage 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?

Description uses a specific verb ('Fetch') and a specific resource ('canonical Markdown source of a page'), clearly distinguishing this read operation from sibling tools like list_docs, update_doc, and delete_doc. The title reinforces but the description adds precision about the Markdown source.

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 access context: public and unlisted pages are open to anyone, while private pages require the owner's lp_ API key. It stops short of explicitly naming alternatives or stating when not to use this tool, 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.

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds meaningful conditional behavior: the response depends on whether an API key is present. This goes beyond the structured data without contradicting it.

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 well-structured sentence that front-loads the main action and provides the essential distinction (anonymous vs keyed access) 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?

For a simple no-parameter read tool with an output schema and clear annotations, the description fully covers the essential context: what is shown, which authentication contexts are relevant, and the conditional plan-status 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?

The tool has zero parameters, so parameter semantics are not applicable; per the baseline, this is set to 4 since the description cannot add param-level 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 uses a specific verb ('Show') and explicitly names the resource ('lucid.page account matrix') and scope ('anonymous vs lp_ API key'), while also covering plan status. It is clearly distinguishable from the doc-oriented sibling 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?

The description gives useful context by noting the behavior differs when a key is present, which implies this is for checking limits/plan status. However, it does not explicitly state when to use this tool versus alternatives or provide any exclusion 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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral details beyond the annotations: the requirement for an lp_ API key, the ordering (newest first), and the cursor pagination mechanism. These complement the safety annotations without contradicting them.

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 verb 'List' and packs essential details (ownership, auth, ordering, pagination) without any unnecessary repetition or filler. It is a model of conciseness.

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

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

For a simple list tool with a full output schema, complete parameter descriptions, and safety annotations, the description adequately covers the necessary context: what is listed, who owns it, the authentication requirement, ordering, and pagination. There are no critical 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?

The input schema provides full descriptions for both parameters (limit and cursor) with 100% coverage. The description's mention of 'cursor pagination' echoes the schema's cursor parameter but does not add new semantic depth beyond what is already stated. The baseline of 3 is appropriate since the schema carries the parameter documentation burden.

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 the specific verb 'List' and clearly identifies the resource as 'documents and bundles owned by the authenticated account.' It also adds distinguishing details like 'newest first' and 'cursor pagination,' which differentiates it from sibling tools such as get_doc (which likely retrieves a single document).

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: it states the required authentication ('lp_ API key') and the behavior ('newest first, with cursor pagination'). While it doesn't explicitly name alternative tools or exclusion criteria, the context makes it obvious that this is the tool for listing owned documents and bundles, as opposed to get_doc for individual retrieval. The lack of explicit alternatives prevents a 5, but the guidance is sufficient for selecting 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?

The description discloses the outcome (creates a page, returns URL), ownership behavior (anonymous vs. authenticated), and the claim process. It does not mention potential side effects like resource limits, but the core behavior is transparent.

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

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

The description is concise, covering essential details in a few sentences without redundancy or unnecessary elaboration.

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 fully covers the tool's behavior, parameters, output, and ownership/claim details, leaving no critical information missing for a typical user.

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?

Each parameter (ttl, title, markdown, visibility) is described with its purpose, defaults, and requirements, adding meaning beyond the schema's field names and types.

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 states the tool's primary function: publishing Markdown to a typeset page and returning a URL. It distinguishes itself from sibling tools by focusing on the publish action, not retrieval or deletion.

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 when to use it (to publish Markdown) and provides context on authentication modes (anonymous vs. API key) and the need to pass the claim token to the user. It does not explicitly compare with alternatives, but the use case is unambiguous.

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 (non-read-only, non-idempotent, non-destructive), the description adds valuable behavioral context: the URL stays unchanged, every update is retained as a revision, and an lp_ API key is required. This meaningfully informs the agent about side effects and auth requirements, without any contradiction to 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 sentence of 24 words that front-loads the action ('Replace the Markdown'), then packs in scope, auth, and revision behavior. Every clause earns its place; there is no fluff, redundancy, or burial of key 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 tool's moderate complexity, 100% schema coverage, presence of annotations, and an output schema, the description covers the essential behavioral aspects: mutation, URL stability, revision history, and auth. There are no obvious gaps that would prevent correct invocation.

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. The description's phrase 'Replace the Markdown' aligns with the markdown parameter, but it adds no additional semantics about slug, title handling, or formatting beyond what the schema already documents. The description neither improves nor degrades parameter understanding.

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+resource: 'Replace the Markdown of a page you own.' It clearly identifies the object (a page/document), the action (replace Markdown), and a scope condition (you own it), which differentiates it from sibling tools like publish_doc (publish vs update) and delete_doc (delete vs update).

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 when to use this tool: when you need to update the content of an already published document. It gives clear context (page ownership, published doc, URL stability) but does not explicitly name alternatives or exclusions, such as 'use publish_doc for first publication.' 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.