findReposBySource

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

With no annotations provided, the description carries the burden of disclosing behavior. It clearly states that it performs exact matching, scans kind-30617 announces, returns npub and gittr URL, and does not fuzzy-match. It omits details like authentication requirements or rate limits, but as a read-only lookup, the disclosed information is reasonably sufficient.

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 three sentences, front-loaded with the core purpose ('Exact reverse lookup'), followed by the return value and use case, and ending with a critical limitation. Every sentence contributes meaning, with no redundant or tangential content.

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 explains the core purpose, return value (npub + gittr URL), and a key constraint (no fuzzy matching), while parameter details are covered by the schema. It does not describe error cases or pagination behavior, but for a reverse lookup tool with a clear schema, the context is adequately 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%, so each parameter already has a descriptive definition. The description adds semantic value by clarifying the exact matching intent for the 'source' field, indicating that both forge URLs and GitHub shorthand are accepted, and emphasizing the exact-match behavior, going beyond the schema's basic 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 immediately identifies the tool as an 'Exact reverse lookup' and specifies what it matches: forge URLs or GitHub shorthand to find Nostr kind-30617 announces. It clearly distinguishes itself from similar sibling tools by emphasizing exact matching, supporting multiple forge types, and explicitly noting it does not fuzzy-match renamed slugs.

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 gives a clear use case ('so you can DM owners when the forge is unreachable') and states it is for exact reverse lookup, implying a different purpose than search or fuzzy matching. However, it does not explicitly name alternative tools like searchRepos or findReposByGithub, so the 'when-not-to-use' guidance is implicit rather than direct.

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