Lotus — AI Citation Intelligence

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

Annotations provide only a title, so the description carries the burden. It discloses two key behavioral traits: the artifact must belong to the authenticated client's domain, and activation enforces a single-active-version rule. However, it stops short of explaining what happens to the previously active version or whether activation is reversible.

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 four sentences, each adding specific value: the core action, a domain constraint, the activation behavior, and a usage guideline. No fluff or repetition, and it is front-loaded with the action verb.

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 tool with one parameter and no output schema, the description is nearly complete. It covers what, when, and key constraints. It does not mention return values or error behavior, but these are not essential for activation and the sibling context is rich.

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% and the only parameter is 'artifact_id'. The description explicitly states 'Activate an artifact by its ID', which clarifies the parameter's purpose and adds meaning beyond the bare schema. It lacks format or example details, but for a single string ID this is adequate.

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 action ('Activate'), the resource ('an artifact by its ID'), and the outcome ('makes the artifact live'). It also distinguishes from siblings like 'approve_artifact' and 'get_artifact' by explaining the uniqueness constraint ('only one version of a given type can be active at a time').

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 explicit usage context: 'Use when an agent needs to deploy an approved artifact to production.' This indicates when the tool is appropriate, but it does not name alternatives or explicitly state when not to use it, which would merit 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 the tool as read-only; the description adds rate limiting details (1/day per IP, 3/week) and differentiates output based on API key availability, which is valuable contextual behavior. 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?

The description is two concise sentences, front-loaded with the primary purpose and then conditional details. Every clause adds value 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 one simple parameter, no output schema, and a read-only annotation, the description fully covers the tool's purpose, behavior, rate limits, and output differences. An agent has enough information to invoke it correctly.

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

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

The schema has one 'domain' parameter with 0% description coverage, but the tool description's first sentence establishes that 'domain' refers to the website being analyzed. This adds necessary meaning, though no format or example is provided.

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 'Analyze a domain's visibility across AI-generated answers' with a specific verb and resource, distinguishing it from the sibling get_* tools which address other aspects of GEO. The purpose is unambiguous.

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

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

The description provides clear context on usage modes (with/without API key) and expected output differences. However, it does not explicitly compare against alternative sibling tools or state when not to use, so it falls short of a 5.

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

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

With no safety annotations beyond a title, the description must carry the behavioral burden. It adds useful context: the domain-restriction requirement and that approval does not make the artifact live. However, it omits potential side effects, idempotency, or prerequisites (e.g., must not already be approved), which is a gap for a write operation.

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 exactly three sentences, each adding value: the primary function, a domain constraint, and the state outcome. It is front-loaded and contains no filler or repetition.

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 tool with no output schema, the description covers the core semantics: what it does, the state change, a constraint, and when to use it. It does not explain return values or error handling, but given the low complexity, this is nearly 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 has only one required parameter (artifact_id) with 0% description coverage. The description says 'by its ID', which clarifies that the parameter is the artifact identifier, but provides no format, source, or validation details. This is minimal compensation for the missing schema description.

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 'Approve an artifact by its ID' with a specific verb and resource. It distinguishes from siblings like activate_artifact by noting 'approved artifacts are ready for activation but are not yet live on the site', making the tool's role in the workflow explicit.

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 explicitly says 'Use when an agent has reviewed a generated artifact and wants to mark it as ready for deployment', giving clear context for when to use. While it doesn't name an alternative tool directly, the state distinction from activation implies when not to use it (for going live).

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 set readOnlyHint=false, so the description carries the burden of explaining the mutation. It adds 'persist it' and 'authenticated client', showing it writes and requires auth. It does not mention side effects, reversibility, or any limitations, which keeps transparency moderate.

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, front-loaded with the core action and return, followed by a compact usage statement. No wasted words or 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?

For a 0-parameter, no-output-schema tool, this description fully covers the function, the persistence behavior, the return shape, and the report's subject matter. It leaves little ambiguity for an agent.

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 are no parameters, so the baseline of 4 applies. The description mentions the return object and report scope, but nothing parameter-specific is needed or possible.

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?

Clear verb+resource: 'Generate a public report link' and 'persist it'. The description specifies the return value shape and the report's content areas (crawler activity, revenue at risk, etc.), distinctly separating it from sibling get_* tools that read data rather than create a shareable artifact.

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

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

Explicitly states when to use it: 'Use when an agent needs to create a shareable report covering the client's full visibility status...' No alternatives or when-not-tos are given, but the context is clear enough to guide selection.

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 readOnlyHint annotation declares the operation is read-only, and the description adds client-scoping, the recency behavior, and the returned fields (content, version, generated_at, status), providing useful context beyond the 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?

Three sentences, each adding necessary information: what it returns, when to use, and the parameter constraint. No filler.

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 tool is simple with one parameter and read-only semantics. The description covers the return fields, the usage context, and the parameter constraint, making it sufficient for an agent without an 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?

The input schema provides only the parameter name and type with no description or enum values. The description compensates by stating the exact allowed values: 'llms_txt' or 'json_ld', which is essential for correct invocation.

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 'Return' and identifies the resource ('most recent artifact') plus its fields and allowed types, clearly distinguishing it from sibling tools like regenerate_artifacts.

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 explicitly states the use case: 'Use when an agent needs to read the generated llms.txt or JSON-LD.' However, it does not mention alternatives or when not to use it, so it lacks the full explicit 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 declare readOnlyHint=true, and the description adds behavioral context about what the return includes: 'cascading metrics with their *_source provenance labels, plus the resulting revenue-at-risk calculation.' Since annotations already cover the safety profile, the description's additional detail about output content earns a 4.

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, front-loaded with the primary action and resource, then provides a concise usage guideline. Every word adds value, with no fluff or repetition 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 zero-parameter read-only tool with no output schema, the description fully covers what the tool does, what it returns, and when to use it. It also conveys authentication context ('authenticated client'), making it self-contained.

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 has zero parameters, so schema coverage is 100% and the baseline is 4. The description does not need to explain parameters; it instead focuses on the tool's purpose and return 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 clearly states the tool's function: 'Return the traffic erosion model for the authenticated client' with specific details about cascading metrics and revenue-at-risk. This distinguishes it from sibling tools like get_artifact or get_bot_activity, which target different data.

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 an explicit use case: 'Use when an agent needs to assess the economic impact of losing traffic to AI-generated answers.' It gives clear context for when to invoke this tool, though it does not mention alternatives or 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?

Annotations already declare readOnlyHint=true, so the description does not need to state safety. The description adds useful context about scope ('authenticated client's domain') and return content, but it does not disclose potential limitations like maximum 'days' value or response pagination. This is adequate but not rich.

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, no filler. The first sentence states the function and outputs; the second gives the usage guideline. Information is front-loaded and every word adds 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?

With one optional parameter, no output schema, and a read-only annotation, the description covers the core purpose and return values. It mentions the domain scope and the output breakdown. It lacks minor details like days range or inclusivity, but for a simple tool this is largely 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 0% for the 'days' parameter, so the description must compensate. It does by explaining the timeframe context ('over the last N days'), which directly maps to the parameter meaning. For a single simple parameter, this is sufficient compensation, though it could be more explicit by naming the parameter directly.

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 'Return AI crawler activity for the authenticated client's domain' with specific outputs listed: total hits, breakdown per bot, most recent hits, and last-seen per bot. This is a specific verb+resource pair that distinguishes it from sibling tools like analyze_geo or get_competitor_actions.

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 includes an explicit 'Use when' clause: 'when an agent needs to assess how frequently AI crawlers visit a site over the last N days.' This provides clear context, though it does not mention alternatives or exclusions, which would be necessary for 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?

Beyond the readOnlyHint annotation, the description discloses that data is raw without classification, returns 'safe fields only', and is scoped to the authenticated client. It also specifies the exact measurement types (citation rate, position, sentiment, etc.), which is rich behavioral context beyond the basic 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 three sentences, front-loaded with the core action and result, followed by the raw-data caveat and usage guidance. Each sentence provides distinct value: what it returns, how it's presented, and when to use it.

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 no output schema, the description covers the essential return content (citation score + week measurements), the filtering ('safe fields only'), the lack of classification, and the intended use case. It is complete for an agent to decide when to invoke this tool and what 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 has zero parameters, so the baseline is 4. The description clarifies that the client is implicit ('for the authenticated client'), which adds meaning about how the tool identifies its subject, despite having no schema parameters to document.

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 'Return' with a clear resource ('most recent citation score') and adds scope details ('measurements from that same week', 'safe fields only', 'Raw data — no healthy/critical classification applied'). This clearly distinguishes it from siblings that might provide classification or different metrics.

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 explicitly states when to use: 'Use when an agent needs to audit how generative engines cite a client' and lists the specific metrics. It implies when not to use (when a classification is needed) via 'Raw data — no healthy/critical classification applied', but does not name an alternative 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 include readOnlyHint=true, indicating a safe read operation. The description adds valuable context by disclosing the API key requirement (pro, growth, or agency), which goes beyond the annotation. No contradiction exists between description and 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 concise sentences, front-loaded with the action ('Return pending and completed competitor actions') and includes only necessary info (auth requirement). 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?

For a simple single-parameter getter with readOnlyHint annotation, the description covers the core functionality and auth. It does not describe return structure, but given no output schema and low complexity, this is mostly sufficient. Minor gap: lacks any mention of rate limits or error cases.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'for a domain' but adds no additional detail about format, constraints, or validation beyond the schema's 'domain' field. The single parameter is minimally elaborated.

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 returns pending and completed competitor actions for a domain, specifying the resource, scope, and type of data. The verb 'return' is specific, and the resource is distinct from sibling tools like get_quick_wins or get_bot_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 implies usage by stating it returns competitor actions for a domain. However, it does not explicitly discuss when to use this tool over alternatives or provide exclusions. The auth requirement is mentioned but not used as a differentiator.

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

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

Annotations declare readOnlyHint=true, already establishing the read-only safety profile. The description adds valuable behavioral context beyond annotations: an API key is required and only structured_data quick wins are supported. These constraints are not present in the annotations and help set expectations, with no contradiction.

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 concise sentences, front-loading the core action ('Generate ready-to-install code') and quickly adding constraints. Every sentence carries useful information with no filler or 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?

The tool has no output schema and 0% parameter coverage, so the description carries a heavier burden. It covers purpose, constraints, and authentication, but leaves the domain parameter's purpose and the expected output format unspecified. Given the tool's simplicity and existing annotations, it is adequate but not 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?

Schema description coverage is 0%, so the description must compensate. It explains the hash parameter via 'identified by its hash', but the domain parameter is entirely unexplained. Since one of two parameters lacks any semantic context, the description only partially compensates for the missing schema 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?

The description clearly states the tool generates ready-to-install code for a quick win identified by hash, specifying a concrete action and resource. It distinguishes itself from list-oriented siblings like get_quick_wins by focusing on code generation, but does not explicitly name alternatives. The structured_data constraint adds useful specificity.

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 a clear condition: only available for structured_data quick wins, and requires a valid API key. It implies the tool is used when you have a hash and need code, but it does not explicitly mention when to use alternatives like get_quick_wins or mark_applied. This gives clear context but lacks exclusions or alternative 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 include readOnlyHint: true, so the read-only nature is disclosed. The description adds an auth requirement (API key) that is absent from annotations, and clarifies the return scope (pending and applied). No contradictions; no additional destructive or rate-limit behaviors need to be mentioned given the tool is read-only.

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, front-loaded with the main purpose and followed by a crucial prerequisite. Every word earns its place; no filler or repetition of schema field names unnecessarily.

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 one required parameter and no output schema, the description covers the core purpose and auth requirement. It does not specify the domain format or response structure, but that is not strictly required without an output schema. Slight gap remains in parameter semantics, as noted.

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 a single 'domain' string with 0% coverage (no description). The description adds 'for a domain,' clarifying that the parameter is the target domain for which to retrieve quick wins, but it does not explain format, examples, or constraints. Given the very low schema coverage, this is a partial compensation but not thorough.

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 'Return pending and applied quick wins for a domain' – a specific verb ('Return') plus resource ('quick wins') and scope ('for a domain'). This distinguishes it from sibling tools like get_quick_win_code (which likely returns code) and mark_applied (which mutates status).

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 the API key requirement (pro, growth, or agency), which is an important prerequisite for using the tool. However, it does not explicitly mention when to use this tool versus alternatives like get_quick_win_code or mark_applied, nor does it state 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?

The description adds behavioral context beyond the readOnlyHint annotation by noting the report is returned even if the share link has expired, and that it is only for slugs owned by the authenticated client. It does not contradict the 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?

Three concise sentences, each serving a clear purpose: purpose, behavioral edge case, and usage guidance. No fluff, 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?

The description covers purpose, usage context, ownership constraint, and expiry behavior. For a simple read-only tool with annotations and a single parameter, this is well-rounded, though it could mention return format or error 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?

With 0% schema description coverage, the description compensates by explaining that the slug (the only parameter) is a share link slug. It adds meaning beyond the bare schema type, though it doesn't detail slug format or provenance.

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 returns the full report payload for a share link slug, with a specific verb, resource, and scope. It also distinguishes itself from the sibling generate_share_link by focusing on reading previously generated reports.

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

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

Explicitly states when to use the tool: when an agent needs to read a report previously generated with generate_share_link, without opening the public URL. It gives clear context but does not list alternatives or exclusions beyond that.

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 annotation readOnlyHint=true already signals a safe read operation. The description adds valuable behavioral details: returns artifacts 'without their content payload,' the meaning of status='' as returning all statuses, the limit default (20) and maximum (100), and that the 'total' field reflects the unfiltered count. These go beyond the annotation and help the agent understand pagination and response semantics.

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 five sentences but every sentence contributes meaningful information: purpose, filtering, limit behavior, total field, and use case. It is front-loaded with the main action and avoids fluff. It could be slightly more concise, but it is well-structured and does not waste 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 low-complexity list tool with only two optional parameters and no output schema, the description is complete. It covers return scope (artifact types, no content), filtering semantics, limit constraints, the total field behavior, and a clear use case. No critical information is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 0%, so the description must fully compensate. It does: for 'status' it explains the exact format (e.g. "pending_review") and the special empty string to return all; for 'limit' it provides the default and max, which is not in the schema. This is essential information that adds significant meaning beyond the schema's bare types and defaults.

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 ('Return') and resource ('artifacts') listing the three kinds (llms_txt, json_ld, defense_nodes) and explicitly excludes content payload. This makes it clear what the tool does and distinguishes it from siblings like get_artifact (which likely returns content) and approve_artifact/activate_artifact (which are actions).

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 an explicit use case: 'Use when an agent needs to discover which artifact IDs are available before approving or activating a specific one.' This clearly states when to use it. It does not name alternative tools explicitly, but the mention of 'before approving or activating' implies the appropriate context relative to sibling tools, so it is strong but not a full 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 description discloses authentication requirements (valid API key), the verification logic, and the fail-safe behavior ('best-effort, fails safe'), which are not present in the annotations. This adds valuable context beyond readOnlyHint=false.

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, front-loaded with the core behavior. 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?

Given the tool has only 2 params and no output schema, the description covers the primary behavior, prerequisites, and failure modes. It lacks explicit parameter definitions, but overall it's adequate for an agent to understand the tool's operation.

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 no descriptions and the description doesn't explain the 'hash' parameter or the 'domain' parameter beyond implying the domain is where the schema is checked. Since schema coverage is 0%, the description should compensate but doesn't.

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 purpose: marking a quick win as applied, with a verification step. It distinguishes from sibling verify_installation by emphasizing it actually marks the quick win (the 'mark' verb) and does so conditionally based on DOM schema presence.

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 clear context that this tool should be used when you want to mark a quick win as applied only after verifying the expected schema is present in the live DOM. However, it doesn't explicitly name alternatives or exclusions, so it stops short of full 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 mark this as destructive, but the description adds important behavioral details: 'Respects a 6h cooldown and the daily generation budget.' It also notes it operates 'for the authenticated client,' disclosing auth scope. These go beyond the annotations and provide critical rate-limit information.

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, front-loaded with the action and artifact types, followed by usage context. Every sentence adds value: the first defines scope, the second provides trigger conditions and constraints. 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 tool with no parameters and no output schema, the description covers the essential aspects: what it regenerates, the constraints (cooldown/budget), and when to use it. The agent has enough context to invoke it correctly and understand the outcome.

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 (empty input schema), so the rubric gives a baseline of 4. The description does not need to explain parameters, and it doesn't, which 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 identifies the tool as regenerating GEO artifacts (llms_txt, json_ld, supporting schema nodes) and distinguishes it from sibling getters like get_artifact by focusing on regeneration. The verb 'Regenerate' plus specific resource names fully capture the purpose.

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 explicitly states when to use the tool: 'Use when an agent needs to force regeneration after changes to the site or to the competitor/advantage configuration.' This gives a clear trigger condition, though it doesn't explicitly mention alternatives or exclusions. The context is sufficient for an agent to decide.

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?

With readOnlyHint=true in annotations, the safety profile is already known. The description adds valuable context by indicating this is a live check (implying network fetch) and specifying the return structure (overall status plus detailed results), going beyond the annotation 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 two sentences, front-loaded with the action and resource. Every sentence earns its place: the first covers purpose and output, the second gives usage context. No redundant or filler content.

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 tool has no output schema, so the description's mention of the overall status values and per-artifact results fully covers return semantics. Combined with the readOnly annotation and usage guidance, the description is complete for an agent to select and invoke this tool correctly.

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

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

The input schema is empty with zero parameters, so the baseline is 4. The description adds no parameter details, but none are needed since there are no parameters to document.

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 begins with a specific verb ('Check live whether') and clearly identifies the resource ('llms.txt and JSON-LD on the authenticated client's domain'). It also lists the exact statuses returned, distinguishing it from sibling tools like analyze_geo by focusing on installation verification rather than analysis.

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 an explicit 'Use when' clause stating the tool confirms GEO artifacts are serving correctly on a client's site. It lacks when-not or alternative tool references, but the context is clear and the tool is niche enough that no exclusions are necessary.

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