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

Despite annotations declaring readOnlyHint=true and destructiveHint=false, the description adds significant behavioral context: it discloses the composite nature (in-process scan of newest contracts), the one-time ~10s discovery scan on first call, and that index_meta reveals scan coverage for transparency. This goes beyond what annotations provide, enhancing understanding of performance and data scope.

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 appropriately sized, front-loaded with a clear purpose, and structured into logical sections (What it does, When to call, Input Requirements, Output). Each section is concise and information-dense, with no wasted words or repetition of schema details unnecessarily.

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 tool has only 2 parameters (both covered), good annotations, and no output schema. The description compensates well by outlining the output structure, mentioning the index_meta coverage disclosure, and the caching behavior. It doesn't elaborate on return fields' semantics, but that's minimal gap given the simple output.

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% for both parameters, so baseline is 3. The description adds value by explaining the query parameter's matching scope (against dURL and name, case-insensitive) and examples, and confirming the limit's default and max, which reinforces but also slightly exceeds schema details. It doesn't introduce new info but effectively clarifies usage.

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: to list and browse TELA apps discovered on-chain, with specific fields (dURL, name, SCID, doc count). It directly addresses the user question 'what TELA apps exist?' and differentiates from siblings by mentioning 'without any external indexer' and providing explicit alternatives (dero_durl_to_scid, tela_inspect).

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 when-to-call scenarios ('when a user wants to explore or search the TELA ecosystem...') and explicitly names alternatives for different needs (exact dURL -> dero_durl_to_scid; inspect specific SCID -> tela_inspect). It also gives input requirements, clarifying that query is optional and for filtering.

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