Nautilinks Backlinks

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

The description discloses that the tool returns explanatory content about the network, purchase flow, pricing, and authentication. It is consistent with the readOnlyHint and idempotentHint annotations, and adds valuable detail about the tool's output 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?

The description is concise, with two sentences that front-load the usage guidance and then list key topics covered. It avoids redundancy and maintains high information density.

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 the essential context: what the tool does, when to use it, and what it explains (pricing, flow, authentication). Since there is no output schema, no return-value details are needed, and the description is sufficiently complete for an agent 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 tool has no parameters, so there is nothing to explain. The description does not need to add parameter information; schema coverage is complete by default.

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 explicitly states the tool's purpose: to explain what Nautilinks does, how its backlink service works, and how an AI agent can use it. It clearly distinguishes this informational tool from the action-oriented siblings like create_order or check_balance.

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 provides explicit usage instructions: 'Use this when the user asks what Nautilinks does...' and even recommends calling it first when unsure about the service. This leaves no ambiguity about when to invoke this tool.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds valuable behavioral context: the balance is applied after discounts, full coverage settles immediately, partial coverage reduces the Stripe remainder, and an API key is required. This goes beyond the annotations.

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

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

Three sentences, each with a distinct purpose: when to use, how the result is used, and a requirement. No redundancy, and the usage guidance 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, no-parameter tool, the description covers everything an agent needs: what it returns, when to call it, how the result affects create_order, and the auth requirement. No output schema exists, but the return value is self-evident.

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 adds context that the balance is scoped to the API key, which clarifies how the tool knows whose balance to return, even though no parameters are in 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?

States a specific verb and resource: 'return the prepaid balance available to this API key'. It differentiates from siblings by explicitly linking to create_order, making its role clear without 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?

Provides explicit when-to-use guidance ('Use this before create_order') and explains how the balance is consumed, which is strong context. However, it does not explicitly state when not to use it or name alternative tools, 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?

The description discloses critical behavioral traits beyond annotations: it can spend the account's prepaid balance immediately, it applies the better of promo/welcome offer, full credit settles immediately while partial credit is held and Stripe charges only the remainder via a payment_url that a human must open and pay, and a card is never charged without human completing checkout. It also mentions the dry_run behavior and the requirement for an API key with 'order' scope. These are significant behavioral details not captured in 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 dense paragraph that front-loads the most critical information (when to use, spending risk) and then covers the flow. It is efficient but could be slightly more structured with bullet points or separate sentences for readability. However, every sentence earns its place, covering usage, prerequisites, payment behavior, and safety. It's not overly long given the complexity.

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 complexity (5 parameters, nested items array, payment flow, dry_run, sandbox), the description is remarkably complete. It covers prerequisites (list_site_articles, check_balance), the payment flow (full vs partial credit, payment_url), safety (dry_run, never imply complete), and authentication scope. The output schema is absent, but the description doesn't need to explain return values since it's a mutation tool. Nothing essential is missing for an agent to call 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 already has 100% description coverage for all parameters, so the baseline is 3. The description adds value by explaining the overall flow (dry_run first, check_balance, payment_url) and clarifying the relationship between parameters (e.g., article_id required when format=lien_insere, promo_code vs welcome offer). It also explains the sandbox_credit_cents parameter's purpose. This goes beyond the schema's individual parameter descriptions, so a 4 is warranted.

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: placing a backlink order when the user has selected placements. It specifies the verb (place an order), the resource (backlinks across catalog sites), and the scope (1 to 20 backlinks). It also distinguishes itself from siblings like list_site_articles and check_balance by explicitly referencing them as prerequisites.

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 explicit usage guidance: 'Use this only when the user has selected placements and wants to place a backlink order.' It also instructs to use list_site_articles first to obtain article_id, to set dry_run=true first for validation, and to call check_balance first to know which way the payment will go. It clearly states when not to use it (never imply purchase is complete) and what alternatives exist.

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 existing annotations (readOnlyHint, idempotentHint, destructiveHint), the description explicitly details what it does not do: no cart, quote, charge, or order. It also narrows the operational scope with 'latest uncited fan-out opportunities', adding useful behavioral context.

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

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

Two tight sentences present the core action, the read-only guarantee, and the follow-up step with zero waste. Information is optimally 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 one-parameter, read-only, no-output-schema tool, the description adequately covers purpose, safety, and the next action. The only notable absence is a description of the returned items' shape, but the promise that they can be passed directly to create_order mitigates that gap.

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

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

The input schema already provides 100% coverage for project_id, and its description even includes the note about passing results to create_order. The tool description adds no further parameter meaning, so the baseline 3 applies.

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

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

The description states a specific verb and resource: turning the latest uncited fan-out opportunities of one AI-visibility project into configured backlink items. It clearly distinguishes this from siblings like list_ai_visibility_projects and frames it as the preparation step for create_order.

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 provides explicit workflow guidance: this tool is for planning and the returned items should be passed to create_order for purchase. It does not explicitly contrast with list_ai_visibility_projects or state when not to use it, but the read-only caveat and next-step routing give clear context.

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, and the description is consistent with that safety profile. The description adds useful behavioral context beyond the annotations by specifying the actual report contents, including environment selection, scopes, and quota consumption, so an agent understands what kind of introspection this tool performs.

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, well-formed sentence front-loads the action and resource, then compactly enumerates the return contents. No words are wasted, no information is repeated from the schema or annotations.

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?

Although there is no output schema, the description adequately describes the high-level return content for a zero-parameter read-only operation. An agent can invoke it correctly and know what to expect from the response without needing further details.

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 complete and parameter semantics have nothing to add. The description appropriately focuses on the returned information instead, satisfying the zero-parameter 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, 'Return', names the resource ('this key's'), and enumerates the exact outputs: live/sandbox environment, scopes, rolling 24-hour order quota, remaining capacity, and supported safety features. This clearly distinguishes it from sibling tools focused on balances, orders, quotes, or sites.

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 its usage context clear: call this tool when you need the API key's own environment, permissions, quota, and safety feature support. It does not explicitly name alternatives or exclusions, but sibling tools have clearly different responsibilities, so no strong when-not guidance is needed.

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

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

The annotations already indicate read-only and idempotent behavior. The description adds useful context about the purpose of metric coverage, which goes beyond the basic 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 concise, using two sentences that convey all necessary information without redundancy. It is well-structured and easy to understand.

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 simplicity (no parameters, read-only), the description is complete. It explains what the tool returns and why it might be needed, providing sufficient context 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?

The tool has no parameters, so the schema provides complete coverage. The description doesn't need to add parameter details, but it could have noted the absence explicitly. The baseline is therefore 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 purpose: it lists valid filter values and metric coverage. The verb 'List' is specific, and the content (niche slugs, categories, etc.) distinguishes it from other 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?

Explicit guidance is provided: 'Call this before filtering when you do not know the exact accepted value' and the explanation of missing metric counts for troubleshooting. This clearly indicates when to use the tool.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds useful behavioral context: it outlines the fulfillment pipeline stages, the fields returned (anchor_text, target_url, published_url), and the API key requirement. This supplements the 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?

Two sentences, front-loaded with the usage trigger, then details. There is no redundancy or filler. Every sentence contributes meaning.

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

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

With no output schema, the description compensates by listing the returned fields and pipeline stages. It also mentions the auth requirement. Given the simple single parameter and read-only annotations, this is sufficiently complete for an agent to call 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?

Schema description coverage is 100%, so the schema fully documents order_id. The description adds a minor note about where the order id comes from (e.g., list_orders or get_quote_status), which is helpful but not essential. 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 fetches per-link status for one order, including the pipeline stages and specific fields returned. It is distinct from siblings like get_quote_status (quotes) and list_orders (list of orders), making its purpose 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?

It explicitly says 'Use this when the user wants publication progress or the live URL for a specific order,' providing a clear condition. It does not list exclusions or alternatives, but the when-to-use context is strong enough to guide an agent.

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 behavior beyond that: the API key requirement, the dependency on create_order's payment_url, and the polling nature of the call.

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-load the usage trigger, then explain the output concept and finally note the authentication requirement. There is slight redundancy between the first and third sentences, but every sentence contributes actionable 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?

For a one-parameter, read-only status-polling tool, the description covers when to call it, what it eventually provides (order_id after conversion), and the required API key. It does not enumerate possible status values or a stopping condition, but the absence of an output schema is not a critical gap here.

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

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

The input schema already documents quote_id as 'The quote_id returned by create_order' with 100% coverage. The description reinforces that dependency but adds no additional meaning about parameter format or constraints, 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: check whether a quote has been paid and retrieve the resulting order_id. It also embeds the tool in a distinct workflow step by referencing create_order's payment_url, which differentiates it from order-status siblings.

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

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

It gives explicit sequencing: call this after create_order returns a payment_url, and poll after handing that URL to the user. It does not explicitly name when not to use it or route to get_order_status, but the intended usage context 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not burdened by safety disclosures. It adds relevant context not in the annotations: a Nautilips API key requirement and the expected shape of the full record (domain, niche, authority metrics, traffic, keywords, pricing). This is useful behavior beyond the structured fields.

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 focused sentences: the first positions the tool with a clear entry condition, the second defines the input and output scope. Every clause adds information; no filler or redundant restatement of the title.

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

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

Given a single documented parameter and no output schema, the description is complete enough: it explains when to call it, what to pass, what kind of record will be returned, and what authentication is required. No critical gap remains for an agent 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?

Schema description coverage is 100%; the sole parameter site_id is described as 'The catalog site id, as returned by search_sites.' The description repeats the use-by-id concept but does not add materially new parameter meaning. A baseline 3 is appropriate because the schema already carries the semantic weight.

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

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

The description states a specific verb and resource: 'Fetch the full catalog record for a single site by id' and enumerates the returned fields. It distinguishes itself from search_sites by clarifying that it targets one site rather than a search result set.

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 opening sentence gives explicit usage context: 'Use this after search_sites when the user needs to evaluate one backlink placement before buying.' This implies search_sites as the collection/search alternative and restricts this tool to post-search evaluation, though it doesn't spell out a formal when-not-to-use list.

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 safety. The description adds value by noting the response contains a 'returned project id', implying what the output yields, and mentions 'owned by this account' as a scoping constraint—details not present in the annotations. No contradiction exists.

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 filler. The primary purpose is front-loaded, and the follow-up usage hint is placed logically after the main action. Every word earns its place, making it a model of conciseness and 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 tool with no parameters and no output schema, the description provides all necessary context: what it lists, the account ownership, and how to use the result. It even mentions the response contains project ids, which is essential for chaining. Nothing an agent needs to call it correctly is missing.

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

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

The input schema has zero parameters, so there is nothing to describe beyond the schema. Per the baseline for 0-parameter tools, a score of 4 is appropriate. The description does not need to clarify any parameters since none exist, and it correctly omits irrelevant parameter details.

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 verb 'List', the resource 'AI-visibility projects', and the scope 'owned by this account'. It distinguishes itself from sibling tools like list_orders by specifying the exact resource type, leaving no ambiguity about what it operates on.

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 explicit usage guidance: 'Use a returned project id with get_ai_visibility_plan to build order-ready backlink items.' This tells the agent exactly how to chain the result with a specific sibling tool. It does not explicitly exclude other tools, but given the simplicity of the tool, the context is sufficient.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond those: results are scoped to the API key and include overall status and totals. It does not mention pagination or limits, but given the annotations cover the safety profile and the operation is a simple list, this is a strong disclosure.

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 with no filler. The condition for use is front-loaded, followed by the scope and content of results, then the sibling alternative and prerequisite. Every sentence contributes distinct, necessary 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?

For a zero-parameter, read-only list operation with annotated safety and clear sibling routing, the description is nearly complete. It states output contents at a useful level (overall status and totals), though it doesn't describe the exact response shape or pagination behavior. Since there is no output schema, a bit more detail on response format could help, but the core invocation context is fully covered.

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 schema description coverage is 100%, so there is nothing for the description to add about parameters. Per the baseline for zero-parameter tools, this is appropriately handled; no parameter detail is missing.

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 precise verb-resource pair: 'List orders placed with this API key, including overall status and totals.' It also differentiates from the sibling get_order_status by framing this as the order-level list while the sibling is for per-link detail. Scope and outcome are unmistakable.

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 says when to use: when the user wants order history or needs to find an order id. It names the alternative get_order_status for per-link detail on a specific id and states the API key prerequisite. This gives an agent clear routing guidance with no inference needed.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat safety. It adds value by noting the API key requirement and the specific return fields (article_id plus ranking queries, positions, impressions) which help the agent understand what to expect beyond the schema. However, it could mention pagination behavior (though limit param is in schema) or the 'sold-once' constraint's implications, which are minor gaps.

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 clear front-loading of the purpose and scope. There's some redundancy with title/tool name, but the description efficiently states what it returns and the next step. It could be slightly tighter, but it's concise and not verbose.

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, the description covers the purpose, return fields, and connection to create_order. The schema covers parameters, and annotations cover safety. It could mention whether results are paginated or sorted, but the limit parameter hints at pagination. The API key requirement is a good addition. Overall, an agent would know how to select and 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?

Schema description coverage is 100%, and both parameters (limit and site_id) are well-documented in the schema. The description adds context about site_id being a catalog site and limit default/max, but it doesn't add new meaning beyond the schema. The description mentions 'one catalog site' which aligns with site_id, but no extra semantic detail. Baseline 3 is appropriate because schema does the heavy lifting.

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 (existing articles on one catalog site), and purpose (choose a page to insert). It distinguishes itself from siblings like create_order and list_orders by specifying that it lists sold-once existing articles, which is a clear differentiator. The returned fields (article_id, ranking queries, positions, impressions) add precision.

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 context on when to use it: when you need to choose a page before placing a create_order with format=lien_insere. It mentions the requirement of a Nautilinks API key, which is a usage prerequisite. However, it doesn't explicitly name alternatives or exclusion conditions (e.g., when not to use this vs. other list tools), so it misses the when-not guidance that would make it 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 readOnlyHint=true and idempotentHint=true, so the description's consistency is fine. It adds value by disclosing the exact fields returned (domain, TF/CF/RD/Moz DA, traffic, keywords, price, shelf, id) and the API key requirement. No pagination or error behavior is described, but the annotations cover the safety profile, so the bar is lower.

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 long but every sentence earns its place: trigger condition, filter options, return fields, id usage, and prerequisite are all packed in without redundancy. Front-loaded with the use-case, it remains well-structured and readable.

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?

Despite 12 parameters and no output schema, the description covers the essential return contract, the id linkage, and the API key need. It also hints at pagination by referencing a total count. A brief example or note about combining filters would be helpful, but for a search tool this is sufficiently 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 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining the price shelf filter with concrete EUR values and noting the id's role for subsequent calls. This enriches the 'shelf' and 'id' parameters, pushing the score above 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?

States a clear verb ('search') and resource ('Nautilinks catalog'), with the purpose of finding or comparing websites for backlinks. It distinguishes itself from sibling tools by noting the returned id is needed for get_site and create_order, leaving no ambiguity about its role.

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 says 'Use this when the user wants to find or compare websites where they can buy backlinks,' giving a clear invocation trigger. It also mentions the API key prerequisite and how the results feed into downstream tools, though it does not explicitly contrast with alternatives (there is no other search sibling) or list exclusions.

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