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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: reads from a specific file, returns terminal state, and explains the push-callback workflow, thus adding value beyond 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?

Well-structured with paragraphs, bullet for args, and returns. Front-loads the main purpose. Concise and clear, though could be slightly more terse.

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 moderate complexity, two optional parameters, no output schema, the description explains the return fields thoroughly. It provides complete context for an agent to use the tool effectively.

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 50% (only task_id described), but the description text explains both parameters: limit with default and max, task_id with filtering purpose. This adds meaning beyond the schema's minimal 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 it fetches async replies from push-mode calls. It distinguishes itself from sibling tools like zyndai_call_agent by specifying the asynchronous nature and the storage mechanism.

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 to use after a push-mode call. While it doesn't name alternative tools for getting synchronous replies, the context is clear and 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?

Goes well beyond annotations (readOnlyHint=false, openWorldHint=true). Details signing with Ed25519, payment auto-settlement on Base Sepolia, fetching agent card, and extracting reply from artifacts. Indicates non-idempotent behavior and potential side effects.

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?

Well-structured with headings (Flow, Tip, Recommended flow, Args, Errors). Each section is concise and informative. No wasted words; every sentence 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?

Given 6 parameters, no output schema, and complex multi-step flow (fetch card, sign, send, handle payment, extract artifacts), the description covers all essential aspects: flow, argument details, return structure (reply from artifacts), error conditions, and prerequisite tools.

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?

Despite 100% schema coverage, description adds major value: explains 'message' vs 'payload' distinction, mode differences (sync blocks, push fires-and-forgets), transport options, and conversation_id for multi-turn. Tips like 'prefer payload for structured input' are highly useful.

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 'Send a signed A2A message to an AgentDNS agent and wait for its response.' It specifies the verb (send, wait), resource (AgentDNS agent), and distinguishes from siblings like zyndai_call_service (different service type) and zyndai_get_agent (read-only).

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 flow: 'Recommended flow: zyndai_search → zyndai_get_agent → zyndai_call_agent.' Explains when to use sync vs push modes and mentions error handling (400, 402, 408, 5xx). Guides agent on alternative tools like zyndai_get_agent for schema.

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 annotations (openWorldHint=true), describes services as stateless, one-shot, no threading, and lists error codes. Adds context that annotations lack (e.g., timing out, authentication needed for paid services). 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?

Well-structured with sections, clear list of parameters and errors. Slightly long but each part adds value. Could be trimmed slightly without loss.

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 6-param tool with no output schema, description covers behavior, error handling, recommended flow, and parameter interaction. Comprehensive for agent selection and invocation.

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

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

Schema coverage is 100%, so baseline 3. Description adds practical advice: mode selection rationale, transport options, message vs payload guidance. Goes beyond 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?

States clearly 'Invoke a service entity (zns:svc:…) registered on AgentDNS' and distinguishes from zyndai_call_agent by noting stateless, one-shot nature. Specific verb+resource with sibling differentiation.

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 a recommended flow (search → get_agent → call_service) and explains when to use message vs payload. Implicitly excludes stateful agents. Could be more explicit about when not to use.

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 details every step performed (kill process, unload plist, delete DNS record, archive keypair, remove active file), which adds substantial context beyond annotations. No contradiction with annotations; the destructive and non-read-only nature is clearly conveyed.

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 well-structured: a one-line summary, a numbered list of steps, a usage note, and a parameter description. Every sentence serves a purpose, and the most critical information is front-loaded.

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

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

Given no output schema, the description covers the full effect of deregistration—on processes, DNS, and local files—plus the precondition for re-registration. It lacks explicit mention of return values or error cases, but for a tool with clear side effects, this is adequate.

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 covers the single optional parameter (keep_keypair) with a clear description. The tool description reinforces this by explaining its effect in step 4, adding context about default behavior (renaming vs. preserving). With 100% schema coverage, the description still adds meaningful nuance.

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 title and description clearly state the tool deregisters a persona and stops the runner. It lists specific steps and contrasts with the sibling zyndai_register_persona, making the 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?

The description explicitly states when to use: 'when the user wants to switch personas or stop being reachable on the network.' It also notes that after deregistration, zyndai_register_persona can be called again. However, it does not explicitly mention when not to use it (e.g., for updating persona, use zyndai_update_persona), though the sibling list provides 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: fallback to .well-known/agent.json, details of what the card contains (identity, endpoints, pricing, schemas), and error codes (404, 5xx). 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 well-structured with sections for Args and Errors. It is somewhat lengthy but every sentence adds value (e.g., fallback, card contents, usage for zyndai_call_agent). It could be slightly more concise, but overall it is organized and informative.

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 explains what the card contains (identity, endpoints, pricing, schemas) and how to use the schemas. It covers the main use case and error scenarios. It could mention that the output is a JSON object, but overall it is complete for a tool retrieving a signed entity card.

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 the schema providing a clear description of entity_id ('AgentDNS entity ID — looks like 'zns:a90cb541…' or 'zns:svc:…''). The tool description adds only minor context ('Get one from search/resolve results'), so the description adds little beyond the schema.

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

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

The description clearly states it fetches the full signed entity card for an agent or service. It specifies the resource (entity card), the verb (fetch), and distinguishes from siblings like zyndai_call_agent, which uses the card to call the agent. The mention of the GET endpoint further clarifies the action.

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

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

The description explains when to use the tool: to retrieve the entity card, especially to obtain input_schema and output_schema for constructing messages for zyndai_call_agent. It also describes fallback behavior. However, it does not explicitly state when not to use this tool compared to alternatives like zyndai_list_agents or zyndai_search_agents, though the context implies it's for a specific entity.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool uses a POST endpoint with no query and describes pagination behavior, which provides useful context beyond 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?

Well-structured with a clear purpose line, technical note, sibling guidance, parameter list with defaults, and practical examples. Every sentence adds value without 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?

Covers all parameters with examples and usage context. However, without an output schema, the description does not detail the structure of the returned list, which is a minor gap given the tool's simplicity.

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 descriptions for all parameters. The description enhances meaning with examples, default values, ranges, and clarification like 'query the federation, not just dns01' for federated.

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?

Clearly states 'Browse all agents and services on AgentDNS with pagination', identifying the verb, resource, and context. Distinguishes from sibling zyndai_search_agents by noting it's for browsing vs targeted discovery.

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 advises 'For targeted discovery, prefer zyndai_search_agents' and provides examples that illustrate appropriate use cases such as 'Browse the network' or 'Show finance agents'.

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 are minimal (readOnlyHint=false, openWorldHint=true, etc.), but the description fully compensates by detailing the multi-step process: API call, listener binding, browser spawn, decryption, and file saving. It discloses side effects (e.g., writing to ~/.zynd/developer.json) and error conditions.

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 well-structured with clear sections (overview, numbered steps, Args, Errors). It is somewhat lengthy but each part serves a purpose. Front-loaded with the tool's action. Minor redundancy (e.g., parameter details repeated in schema and description).

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 login flow, dependencies, error states, and relationship to sibling tools. It lacks explicit mention of return value (no output schema), but error handling compensates. For a complex tool, it 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 description coverage is 100%, so the baseline is 3. The description adds minimal extra context beyond the schema (e.g., 'suggested developer display name' vs. schema's 'Optional developer display name...'). No significant semantic enhancement.

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: 'Onboard the user with Zynd via the registry's restricted-mode browser flow.' It details the step-by-step process and positions itself as the prerequisite for zyndai_register_persona, clearly distinguishing from sibling tools.

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

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

The description provides clear context: it is the first step, typically followed by 'create my persona' invoking zyndai_register_persona. It also explains error handling (e.g., force overwrite, using zyndai_whoami). However, it does not explicitly list scenarios when not to use this tool or compare to all siblings.

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. The description adds context about reading from a specific file (~/.zynd/mailbox/<entity_id>.jsonl) and filtering for pending status, which goes beyond 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 well-structured with a clear purpose, workflow, and parameter info. It is efficient without unnecessary verbiage.

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?

While the workflow is explained, the return format is not described. The tool returns entries with status=pending, but fields like sender, content, timestamp are not mentioned. Without an output schema, this is a 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?

Schema coverage is 100%, but the description and schema both elaborate on the 'since' parameter with usage details (ISO timestamp, polling). This adds value beyond the bare schema.

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

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

The description clearly states the verb (list), resource (messages), and constraint (pending). It distinguishes from sibling zyndai_respond_to_request, which handles replies.

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 workflow is provided: step-by-step instructions on when to call this tool, how to process results, and which sibling tool to use next. Also explains the optional 'since' parameter for polling.

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 thoroughly explains side effects: keypair derivation, DNS registration, spawning background process, and installing launch agent. It also documents errors and refusal conditions. Annotations indicate idempotentHint true, which is consistent with the description that subsequent calls return existing details without duplication. 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 well-structured with bullet points and sections. Every sentence adds value, and it is front-loaded with the core action and critical warnings. No 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?

Despite no output schema, the description details success steps, resulting API endpoint, mailbox location, and references sibling tools for further actions. The agent can fully understand the outcome and next steps.

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% and the description adds significant context: name auto-suffixes '-claude-persona', summary defaults, pricing_usd defaults to free, pricing_currency defaults to USDC. It also clarifies when and how to set each parameter.

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 that the tool registers a Claude persona on AgentDNS and starts a background A2A server. It distinguishes this one-time action from sibling tools like zyndai_deregister_persona and zyndai_update_persona.

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 (one-time per user), what to do if already registered (call deregister), and prerequisites (env variables, login). It also guides on when to set pricing_usd only if user explicitly asks to charge.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by listing the specific return fields (entity_id, name, summary, category, tags, entity_url) and mentioning the error code 404 for missing agents. 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 very concise, with a clear first sentence, a format explanation, an example, a list of returned fields, and a brief error note. No unnecessary words, well-structured for quick parsing.

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 there is no output schema, the description compensates by listing all returned fields and the error scenario. It also explains the tool's place in the workflow (producing entity_id for other tools). This makes it complete and self-contained for an agent to understand how to use it.

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 only one required parameter, fqan, with a schema description that covers format. The description adds an example ('stocks.alice.zynd') and explains the outcome, but since schema coverage is 100% and already detailed, the description adds marginal extra 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 action: resolving a fully-qualified agent name to an entity_id. It provides the FQAN format, an example, and the list of returned fields, making it easy to understand what the tool does. It also distinguishes itself from sibling tools like zyndai_get_agent by noting that the returned entity_id can be passed to those tools.

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

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

The description explicitly states when to use the tool (when you have a FQAN and need an entity_id) and how the output can be used with other tools (zyndai_get_agent, zyndai_call_agent). It does not explicitly mention when not to use it, but the context is clear and provides sufficient 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 indicate a non-read, non-destructive write operation. The description adds significant context beyond annotations: it explains that the reply is delivered by the persona-runner, looks up the original sender on AgentDNS, and POSTs an Ed25519-signed AgentMessage with metadata.in_reply_to. It also lists potential errors and prerequisites, fully disclosing behavioral traits.

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 well-structured: summary, usage instructions, examples, delivery details, parameter list, and error cases. Every section adds value. It could be slightly trimmed (e.g., the delivery details might be overkill), but overall it's efficient and clear.

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 no output schema, the description covers the return behavior (signed message delivery), error conditions, and prerequisites (e.g., needing an active persona). It references other tools for error resolution, making it self-contained and complete for the given complexity.

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 baseline is 3. The description adds value by clarifying that 'response' is ignored when approve=false, and that 'message_id' comes from zyndai_pending_requests. It also explains errors related to parameters. This extra context justifies a 4.

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

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

The description clearly states the tool sends a reply to or rejects an incoming persona request. It uses specific verbs ('Send a reply', 'reject') and distinguishes itself from sibling tools like zyndai_pending_requests (which lists pending requests) and zyndai_call_agent (which initiates calls).

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 instructs to confirm with the user before calling, provides a template for confirmation, and gives clear examples for approval and rejection scenarios. This is exemplary guidance for when and how 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?

The description goes beyond the annotations by detailing the underlying API endpoint (POST /v1/search), the hybrid search mechanism, filter composition behavior, and the returned fields. No contradictions with annotations.

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

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

The description is well-structured: it begins with the purpose, then provides technical details, return format, and usage examples. Every sentence adds value, 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?

Given the 13 parameters, no output schema, and the presence of sibling tools, the description is complete. It covers behavior, return fields, provides examples, and links to related tools. No major gaps.

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

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

With 100% schema description coverage, the baseline is 3. However, the description adds significant meaning through examples for each parameter (e.g., query, category, tags, enrich, federated) and explains how filters combine. This greatly aids the agent in selecting appropriate parameters.

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: 'Search the AgentDNS network for agents and services.' It uses a specific verb (search) and resource, and distinguishes from sibling tools by mentioning hybrid search, filters, and the ability to browse without a query.

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 guidance on when to use the tool (e.g., 'Omit `query` and pass only filters to browse the network') and includes examples of various parameter combinations. It does not explicitly state when not to use it, but the context implies differentiation from siblings like zyndai_list_agents.

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?

Discloses critical behaviors beyond annotations: killing and respawning runner on URL change, replacement of PID in config file, and that defaults are not re-asserted. Annotations indicate idempotent, non-destructive, not read-only, which align with the description.

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?

Well-structured with bullet points and sections, front-loaded with main purpose. Slightly verbose but each sentence adds value. Could be tightened slightly.

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?

No output schema and no description of success response. Errors are covered. Prerequisites and behavior are well-documented, but missing return value expectations. Acceptable for a patch tool 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 coverage is 100%, but description adds significant context: tags have auto-merged defaults, entity_url triggers restart, pricing_usd=0 means free. This goes beyond schema descriptions and helps agent select correct parameter values.

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 it patches the active persona's AgentDNS record without changing entity_id, lists specific use cases (URL rotation, pricing changes, summary/tags updates), and distinguishes from sibling tools like register and deregister.

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 describes when to use (tunnel URL rotation, start/stop charging, refresh summary/tags) and includes fallback behavior. Also mentions prerequisites (must have active persona) and error conditions.

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 it as read-only, idempotent, and non-destructive. The description adds value by detailing the specific return fields (developer status, ID, key, persona, registry URL, filesystem locations), providing behavioral context beyond the annotations. No contradictions.

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 and well-structured: a clear first sentence stating purpose, a sentence on when to use, and a bullet-like list of return values. No unnecessary words, and the most important information is front-loaded.

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

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

Given no parameters, no output schema, and simple context signals, the description is fully complete. It covers purpose, usage, and return values comprehensively. The agent has all needed information to decide and invoke 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, and the schema coverage is 100% (empty properties). Per guidelines, baseline is 4 for zero parameters. The description does not need to explain parameters, but it compensates by describing the return values, which is helpful. Could be higher if it explicitly stated 'no parameters required'.

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 that the tool reports the user's current Zynd identity state, including login status, developer key, and persona registration. It uses specific verbs ('report') and resources ('identity state'), and implicitly distinguishes from siblings that perform actions like login or registration.

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 usage guidance is provided: 'Use this whenever the user asks "who am I on Zynd?", "am I logged in?", or as a quick health check before calling other tools.' This tells the agent exactly when to invoke it and suggests using it as a prerequisite, which is exemplary.

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