AgentNexus.App

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: concrete rate limits (100/day anonymous, 1,000/day free key, 50,000/day Agent Pro), the returned fields (slug, endpoint, auth, formats, pricing, 0-100 reliability), and the no-match fallback behavior.

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 dense sentences, front-loaded with the purpose and immediately followed by the return shape and routing rule. The rate-limit sentence is useful for planning but is the least essential clause, keeping it just short of a 5.

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 4-parameter discovery tool with an output schema and full annotation coverage, nothing needed to invoke it correctly is missing: purpose, fallback semantics, alternative route, and quota constraints are all stated.

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 need, limit, category and min_reliability are already fully documented, including the enum and list_categories cross-reference. The description adds only indirect meaning (e.g. the reliability score tied to min_reliability) without new syntax or format detail, 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?

States a specific verb and resource: 'Map a plain-language goal ... to callable APIs, MCP servers or CLIs.' It also names the sibling it is not (search_registry), so an agent can distinguish it from search_registry/list_entries 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 an explicit routing rule: 'For a known keyword or slug, use search_registry.' It also covers the empty-result case by describing coverage='none' plus fallback matches, so the agent knows both when to call it and what it means when nothing fits.

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, openWorldHint and destructiveHint, so the safety profile is covered and the description's restatement of 'read-only and idempotent' is mild redundancy. It does add genuinely new behavior: idempotency holds only until the health probe changes, the response carries a 6-hourly probe plus invocation details, and an unknown/unapproved slug is an error rather than an empty result.

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 core action and the precondition before the alternatives, and every sentence carries routing or error information. The middle sentence enumerating returned fields (endpoint, auth mode, pricing, health probe, etc.) is the longest and is partly redundant given an output schema exists.

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 single-parameter lookup with full annotation coverage and an output schema, this covers everything an agent needs: what it returns, why it differs from listing tools, when not to use it, and the failure mode for a bad slug. Nothing material 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 description coverage is 100% and the slug schema is already rich (case-sensitivity, length, approved-only), so baseline is 3. The description adds usage-level meaning the schema does not: the slug should come from a prior tool result rather than being guessed, and only approved entries resolve. It stops short of adding format or validation 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 ('Fetch the full record of ONE approved registry entry'), scopes it to an exact slug, and explicitly positions it as the single-record lookup that takes no filters or paging. An agent can distinguish it from search_registry, discover_capabilities and list_entries 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 an explicit precondition ('whose exact slug you already have'), names where the slug comes from, and routes the agent elsewhere when the precondition fails: search_registry for keywords, discover_capabilities for plain-language needs, list_entries for the whole catalogue. It also warns not to guess a slug.

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?

Annotations cover the safety profile (read-only, idempotent, non-destructive), yet the description adds traits annotations cannot express: literal substring matching with no goal interpretation, alphabetical rather than relevance ordering, no pagination beyond limit, and that an empty result set is valid rather than an error. These are exactly the runtime surprises an agent needs warned about.

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 routing decision, then matching semantics, ordering caveats and the empty-result rule — all high-value. The sentence describing the {count, results[]} shape duplicates the output schema, which is the one piece that doesn't earn its place.

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

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

For a three-param read tool with a full output schema and complete annotations, the description closes the remaining gaps: matching mode, sort order, pagination limits and the meaning of an empty result. An agent can call this correctly without further probing.

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 the schemas already spell out substring matching, the 120-char cap, stripped characters, the empty-query browse behavior and the 1-50 limit. The description's parameter content ('optionally narrowed to one category', 'raise limit (max 50)') largely restates that, so 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?

States a specific verb (keyword lookup) plus resource (Agent Nexus registry) and immediately bounds the scope to literal text, not intent. It explicitly distinguishes itself from discover_capabilities, list_entries and get_entry by naming each sibling's job.

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 an explicit when-to-use condition ('when you already know what to look for') and three named alternatives with the condition that selects each: discover_capabilities for plain-language needs, list_entries for catalogue walks, get_entry for a known slug. Nothing is left 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?

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.