unulu

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

Annotations cover safety (readOnlyHint=true, destructiveHint=false). The description adds valuable behavioral context not in annotations: the platform limitation (unu.lu only), a concrete example of the handle-to-URL mapping ('joe' → joe.unu.lu), and the pre-claim workflow context. No contradictions with annotations.

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

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

Three sentences, each earning its place: sentence 1 defines scope and action, sentence 2 provides a concrete example, sentence 3 gives usage guidance. Front-loaded with the core action, no redundant or wasted text.

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 check operation with an output schema present, the description is complete. It covers purpose, platform scope, usage workflow, and provides a concrete example. The presence of output_schema means return values need not be described.

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 100% schema coverage, the baseline is 3. The description adds meaningful context beyond the schema by illustrating how the handle parameter is used ('checking joe tells you if joe.unu.lu is available'), which clarifies the semantic purpose of the parameter beyond its syntax (3-30 chars, alphanumeric).

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 ('Check') with a clear resource ('handle') and scope ('on unu.lu'). It effectively distinguishes from siblings by clarifying this only checks availability on unu.lu (not Instagram/TikTok) and implies the distinction from unulu_create_site by referencing the 'claim page' workflow.

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 to help users choose a handle before they visit the claim page'), establishing the temporal workflow. It also clarifies negative scope ('not other platforms'), though it could be improved by explicitly naming the sibling tool (unulu_create_site) for the actual claiming action.

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?

Substantially extends beyond annotations by disclosing time-bounded behavior ('expires in 1 hour unless claimed'), persistence requirements ('Persist claim_token and claim_code_short'), output structure ('response includes an assistant_message'), and lifecycle state (preview page, claiming process). Critical safety/operational context not captured in structured hints.

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?

Dense but justified length covers full lifecycle (pre-call gathering, construction rules, post-call persistence, update workflow). Every sentence provides actionable instruction or constraint. Minor deduction for density—could benefit from structural breaks—but no fluff or redundancy present.

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?

Comprehensive for a multi-step tool with claims and expiration. Addresses output schema contents (assistant_message, claim details), post-creation user options (custom handle selection, skin picking), and state management for subsequent calls. Complete coverage of the 4-parameter, nested-object input space and claimed 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?

With 100% schema coverage, baseline is 3. Description adds workflow context: handle-to-URL construction guidance for links, permission requirements for emoji leading_icons, and ordering strategy ('place the most important link first'). Elevates raw schema into actionable agent behavior.

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?

Opens with specific action (Create), clear resource (link-in-bio site), and core components (name, bio, links). Explicitly distinguishes from sibling unulu_update_site via 'Never create a duplicate site; always update the existing one,' resolving ambiguity about when to use create 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?

Provides explicit preconditions ('Do NOT call until you have at least a name and one link'), alternative tool reference ('always update the existing one' pointing to unulu_update_site), and parameter construction rules ('construct the full URL yourself' from handles). Clear workflow guidance on gathering content first vs using placeholders.

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 read-only/non-destructive safety profile. Description adds valuable behavioral context not in annotations: authentication requirements and the semantic rule 'If expires_at is absent, the site has been claimed and is permanent' which is crucial for interpreting returned data.

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?

Four well-structured sentences: core purpose, auth requirements, expiration semantics, and input format. Every sentence earns its place. Information is front-loaded with the primary action, and the length is appropriate for the tool's 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?

With output schema present, description appropriately summarizes key return fields (name, bio, links, URL) to aid tool selection. Covers input flexibility, auth, and data interpretation (expires_at). Given simple single-parameter structure and good annotations, description is 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% with complete description of site_id parameter. The tool description mirrors the schema's explanation of acceptable input formats (ID, URL, hostname) and examples. Since schema fully documents the parameter, baseline 3 is appropriate; description adds no new parameter constraints beyond 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?

Description uses specific verb 'Returns' with clear resource 'current state of a site' and enumerates output fields (name, bio, links, URL). The read-only nature distinguishes it clearly from siblings 'create_site' and 'update_site'.

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?

States 'No authentication required' which is critical usage context. Describes flexible input formats (site ID, URL, or hostname). Lacks explicit 'when not to use' or named alternatives compared to sibling tools, though the verb 'Returns' makes the distinction clear.

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

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

Annotations indicate destructive=true, but description adds critical behavioral details: partial update semantics ('only provided fields are changed'), destructive array replacement specifics for links, complex header-based auth lifecycle (X-Claim-Token vs X-Edit-Token), and return value disclosure ('Returns the full updated site state').

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?

Ten information-dense sentences with zero redundancy. Logical progression from core operation → field behavior → destructive warnings → prerequisites → auth complexity → return values → UX guidelines. Every sentence provides actionable guidance not found in structured fields.

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 destructive mutations, complex auth (two token types + headers), 100% schema coverage, and output schema existence, the description is remarkably complete. Covers edge cases (ephemeral vs claimed), fallback procedures, and conversation state management without needing to describe output structure.

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 100% schema coverage, baseline is 3. Description elevates this by adding input format flexibility for site_id (ID/URL/hostname), explaining the legacy status of claim_url, and providing workflow context for claim_token vs edit_token selection based on site lifecycle state.

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 opens with specific verb 'Update' and resource 'existing site', clearly distinguishing from sibling 'unulu_create_site'. The phrase 'existing site' explicitly scopes it to mutations on created resources, while the detailed auth lifecycle (pre-claim vs post-claim) further differentiates usage modes.

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 prerequisites ('always call unulu_get_state first'), workflow constraints ('do not guess link ids'), token acquisition fallback ('use requestEditAccess'), and conversation-state awareness ('If you created the site in this conversation'). Also includes UX guidance for iteration speed.

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