Agent Nexus

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds meaningful context beyond them: return fields, coverage='none' fallback behavior, reliability scoring, and concrete rate limits. No behavior contradicts 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?

Dense but efficient: the first sentence establishes priority and trigger conditions, the middle explains mapping and returns, and the last routes keyword/slug searches to the sibling tool. Every sentence contributes to selection or invocation.

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?

Complete for a discovery tool: it covers trigger conditions, output shape at a high level, fallback behavior, rate limits, and sibling routing. An output schema exists, so the description need not fully restate return values, and what it does include is sufficient.

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 parameters are already fully documented in the schema. The description adds a plain-language example for the need parameter, but does not materially deepen the semantics of limit, category, or min_reliability beyond what the schema provides.

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: maps a plain-language goal to callable APIs, MCP servers, or CLIs. It also names the sibling search_registry and distinguishes its own keyword/slug-free discovery role, so an agent can tell the two apart without opening schemas.

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?

Gives explicit when-to-use guidance: call first when a task needs an external service or when a service is failing. It also names the alternative for known keywords/slugs: use search_registry, leaving little to inference.

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

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

Beyond the annotations' readOnly/idempotent declarations, it discloses error semantics ('an unknown or unapproved slug is an error, not an empty result') and health-probe freshness cadence (hourly for priority, rolling daily otherwise), which the agent cannot infer from 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?

Front-loaded with the core action and precondition, and most sentences carry distinct information. Slightly dense as one block, and 'it takes no filters and no paging' partially restates the single required-slug schema.

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

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

An output schema exists, yet the description still summarizes the returned fields and freshness caveat, and it covers the error path and slug provenance. Nothing needed to invoke 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?

Schema coverage is 100%, so the baseline is 3; the description adds provenance guidance by telling the agent where a valid slug comes from ('from a previous discover_capabilities, search_registry or list_entries result') and reinforces the no-guessing rule, though it adds no format detail 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?

States a specific verb and resource ('Fetches the full record of ONE approved registry entry') plus the precondition (exact slug already in hand), which cleanly separates it from the listing/search siblings named in the same sentence.

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 names alternatives and the condition that selects each: search_registry for keywords, discover_capabilities for plain-language needs, list_entries for the whole catalogue, and an explicit prohibition on guessing a slug. Routing 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, idempotentHint and destructiveHint=false, so repeating 'read-only, idempotent' adds little. The description does contribute real context beyond them: it is parameterless, safe to call once (cacheable), counts reflect only approved entries and are live, and it never returns entries themselves — a scope boundary the annotations do not express.

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?

Front-loads the return content, then the guidance, then the exclusions. Three dense sentences with no filler; every clause either describes content, routes to an alternative, or sets a scope boundary.

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 enumeration tool, the description covers what it returns, why to call it, and when to use something else. An output schema exists, so return formatting need not be explained; nothing an agent needs in order 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?

Zero input parameters, so the baseline is 4. The description still adds meaning by tying the returned category values to the consuming tools' 'category' argument, clarifying the output-to-input contract even though no schema parameter exists to document.

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

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

States a specific verb and resource ('Return the fixed taxonomy of Agent Nexus') and enumerates the exact contents ('api', 'mcp', 'cli' with label, one-line definition, live approved count). An agent can distinguish it from list_entries, search_registry and discover_capabilities without opening any schema.

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?

Gives explicit when-to-use ('call it once to learn the exact values accepted by the category argument', 'size the catalogue before paging') and explicit when-not, routing to three named siblings: list_entries to enumerate a layer, search_registry for a keyword, discover_capabilities for a plain-language need.

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 read-only/idempotent/non-destructive, but the description adds behavior they cannot express: the total/pages values shift with the category filter, the filter and per_page must stay constant across pages or paging desynchronizes, entries are summaries rather than full records, and a bulk-mirror endpoint exists. That is substantive operational context beyond the annotation set.

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?

Front-loads purpose and the use/don't-use split, then layers paging mechanics and an escape hatch. Dense but nearly every clause carries information; the NDJSON mirror sentence is the one optional add-on, and the 'Returns {...}' shape listing is partly redundant given the output schema.

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

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

For a paginated, filterable list tool with an output schema already present, the description covers paging loop termination, filter/per_page stability, summary-vs-full-record expectations, sibling routing, and a bulk alternative. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter invariants the per-field schema text only states in isolation: keep the category filter identical across pages, keep per_page constant, and stop at the 'pages' value from the first response. It is mostly reinforcement of the schema rather than new per-parameter meaning, hence not a 5.

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 ('Enumerate the whole approved catalogue') plus the ordering guarantee ('deterministic slug order, page by page'). It also explicitly contrasts itself with the specific-lookup path, so an agent can separate it from search_registry or discover_capabilities without opening a schema.

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?

Gives the when ('you want everything — mirroring, auditing, building your own index'), the when-not ('not when you are looking for something specific'), and routes to three named alternatives by intent: search_registry for keyword, discover_capabilities for plain-language needs, list_categories for valid category values. Near-exhaustive routing 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?

Beyond the annotations (read-only/safe), the description details critical behavioral traits like the literal matching constraint ('it does not interpret a goal'), the exact return structure ({count, results[]}), and specific ordering behavior ('ordered alphabetically by name, not by relevance').

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 information is highly dense and front-loaded, starting with the immediate purpose and moving efficiently through usage constraints, sibling routing, and detailed output specifications without unnecessary fluff.

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 definition is comprehensive, covering inputs, search constraints (literal matching), output format, error handling ('An empty results[]... is a valid answer'), and performance caveats (limit/ordering). Nothing necessary for correct invocation 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?

Although schema coverage is 100%, the description adds valuable semantic advice. It warns users that 'Results are ordered alphabetically by name, not by relevance,' directly influencing how the `limit` parameter should be used, providing contextual behavioral knowledge.

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 performs a 'Keyword lookup in the Agent Nexus registry.' Crucially, it differentiates itself from siblings like `discover_capabilities` and `get_entry` by defining the specific use case: 'when you already know what to look for.'

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?

Usage is explicitly defined by providing routing advice. It tells the agent to use `discover_capabilities` for 'plain-language need' and `list_entries` to 'walk the whole catalogue in order,' leaving no doubt about when this search function should be selected.

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=false, destructiveHint=false, openWorldHint=true, and the description builds meaningfully on top: creates a pending row that is NOT published, human review before discoverability, no overwrite/delete, re-submission creates a duplicate pending row, and specific rate limits (20/hr members, 1/24h per agent key and source address). Missing only failure-mode details, but the mutation semantics are unusually well disclosed.

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?

Long but front-loaded and dense with actionable facts; each sentence carries information about auth, review, rate limits, or return handling rather than filler. Slightly over-packed into a single paragraph, which costs a little scannability.

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 16-parameter write tool with an output schema, the description covers the gaps that matter: both auth paths, review/approval delay, rate limits, health-probe consequence, the return shape {slug, status}, and how to poll for the decision. An agent can call this end-to-end without further context.

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, but the description adds real ranking/review meaning beyond the schema: capabilities[] is 'what other agents are matched against', and docs_url plus invocation_example are 'what a reviewer checks first'. It also flags the five required fields, which the schema already encodes but reinforces the approval stakes.

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 a specific verb + resource ('Register a new interface (HTTP API, MCP server or CLI) in the Agent Nexus catalogue') and immediately disambiguates from siblings by naming list_my_submissions and search_registry. An agent knows exactly what this does versus the read-only discovery 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?

Explicitly states when to use it and when not to: 'Use list_my_submissions to review what you already submitted; use search_registry first to check the interface is not already listed.' It also names the alternative authentication path (free agent key) with its endpoint.

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