Index Agentica

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

Annotations already cover read-only, idempotent, non-destructive, non-open-world. The description adds valuable behavioral context beyond annotations: it details the return payload by type (comparison table, stack components, skill SKILL.md and download links) and states that unknown ids return an error with suggestions. That's substantive transparency about output shape and failure modes that no structured field provides.

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?

One dense but well-structured paragraph front-loaded with purpose, then payload, then edge case. Every sentence earns its place, though the long parenthetical listing metadata fields is slightly heavy for a single breath.

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 rich output schema exists, the description needn't explain every return field, yet it goes further by characterizing the shape per item type and the error case. It omits explicit guidance on when to prefer get_content over get_entry, which would complete the routing picture, but it is otherwise sufficient for correct 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% and all three parameters are documented in the schema with descriptions and an enum. The description reinforces that type and id are the key inputs but adds no new syntax beyond what the schema already provides. Baseline 3 is appropriate when the 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 (Fetch), resource (Index Agentica long-form item), and the keying (by type and id as returned by search). The title and description together distinguish it from siblings like get_entry and search.

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?

Implies this is the follow-up to search by noting the id is 'as returned by search', and describes error behavior for unknown ids. It doesn't explicitly say when to use get_content vs get_entry, which would be useful given the sibling, but the context is 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 already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful behavior: it returns the complete field set in a single call and returns an error with suggested ids for unknown ids, which tells the agent how failure manifests.

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 front-loaded sentences that state the operation first and details second. The long enumeration of returned fields is somewhat redundant given an output schema exists, but it does not obscure the core instruction.

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 read with full annotations and an output schema, the description covers the identifier format, the success shape, and the failure mode. Nothing needed to invoke or interpret the call 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% and the pattern plus maxLength fully constrain the single id parameter, so the schema does the heavy lifting. The description reinforces it with a kebab-case example ('model-context-protocol') but adds no semantics beyond the schema's own description.

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 one Index Agentica entry by its id') and pins the identifier format with a concrete example. It is clearly distinguishable from siblings like search (which finds ids), list_categories, and get_content.

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 implied rather than stated: the id must come from a prior search, and the mention of an error with suggested ids hints at a recovery flow. It never explicitly says 'use search first' or contrasts itself with get_content, so the agent must infer the routing.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds little beyond this, and its field list largely duplicates the existing output schema, leaving the bar for extra behavioral context only partially met.

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, no filler, with the resource scope front-loaded before the chaining instruction. Every clause carries information an agent can act on.

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 tool with annotations and an output schema, the description supplies everything needed to select and invoke it. Absent details such as ordering or pagination are minor given the small, bounded nature of a category listing.

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 takes zero parameters, which sets the baseline at 4. The only parameter-like mention (slug) is a value consumed by a different tool, not an input here, so there is nothing further to clarify.

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 precise verb and resource ("List all Index Agentica categories") and enumerates the returned fields (slug, name, description, entry count, links), so the agent knows exactly what it gets. The tie-in to search via slug also implicitly separates it from get_content/get_entry/search, which operate on entries, not categories.

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 tells the agent how to chain this tool with search ("Use a slug as the category filter for search"), which is real when-to-use guidance. It does not state any when-not conditions or name the sibling tools directly, so it stops 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?

Beyond the annotations, it discloses substantial behavior: similar requests merge with a per-client vote, nothing is listed automatically, the Curator verifies each request, and hard limits of 5/hour and 20/day apply. These are exactly the operational facts an agent needs and are consistent with readOnlyHint=false and idempotentHint=false.

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 core action is front-loaded in the first sentence, followed by behavior, endpoints, limits, and the search-first nudge. Every sentence carries information, though the two public-queue URLs are more contextual than essential for invocation, keeping it slightly long.

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 mutation tool with annotations and an output schema, the description covers purpose, side effects (merge/vote/moderation), limits, and the recommended prerequisite search. Return values are handled by the output schema, so 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 description coverage is 100%, so the schema already documents all five parameters including examples for 'wanted' and the full category list. The description reinforces the domain of the request but adds no syntax or format detail beyond what the schema provides; the baseline of 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 first sentence states a specific verb and resource: 'Ask Index Agentica to add something that is missing,' with concrete examples (skill, harness, MCP server). It clearly distinguishes itself from siblings like search and get_entry, which retrieve existing entries rather than request new ones.

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 names the alternative ('Search first to check it is not already listed') and gives the condition that selects it, plus the when-to-use context of requesting missing items. The rate limits and moderation gating further scope how often it can be used.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: which fields are matched, that results are ranked best-first, and that each result carries type, relevance score and links. It does not cover pagination or result-count behavior, but the added matching/ranking details are substantive.

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 dense paragraph that front-loads the resource scope, then matching behavior, then filters, then the sibling hand-off. All sentences carry information, though the opening inventory of content types is slightly list-heavy.

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 an output schema present, return-value details are not required, and the description still notes the shape (type, relevance score, links). Combined with full schema coverage and annotations, an agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: tags require ALL given tags to match, category implies type entry, and an empty query plus a filter lists everything in that filter. These are non-obvious interaction rules that earn a bump 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 specific verb (search) and resource (the Agentica index of agent-usable resources and long-form content), and enumerates what is searched over. It is clearly distinguishable from the get_* siblings, which it names explicitly.

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 routes the agent: use get_entry for type entry and get_content with type+id for long-form items when full details are needed. It also documents the edge case of an empty query with a filter, which is genuine when-to-use guidance.

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