CodeAtlas

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that (no return shape, no notes on unknown slugs), which is acceptable given the annotation coverage but not a value-add.

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 front-loaded sentence with no filler. The enumerated slugs duplicate the schema enum, which is mild redundancy but does let the agent pick a valid value without opening the 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 single-parameter, read-only lookup with rich annotations, the definition is nearly sufficient. With no output schema, it could say what a returned service record contains, but that gap is minor for a deterministic slug lookup.

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 single slug parameter is fully documented with an enum, so the schema carries the load. The description merely repeats the three enum values already present in the schema, adding no format or semantics beyond it.

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 one CodeAtlas service') and scopes it to a stable slug, which implicitly separates it from codeatlas_list_services and codeatlas_search_services. It stops short of naming those siblings, so the differentiation is inferred rather than stated.

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 only implied: the tool requires a known slug, so an agent can infer it is the direct-lookup path versus list/search. There is no explicit when-to-use statement, no exclusion, and no mention of the alternative tools for discovery.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing what data comes back (slug, description, capabilities, delivery timeline, URL), which is not available in annotations and only partly inferable from the schema.

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 front-loaded sentence that names the collection first and then the payload. No filler, no redundancy with the title.

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?

There is no output schema, so the description's enumeration of returned fields is doing necessary work and largely covers the return contract. The remaining gap is routing context versus the get/search siblings, minor for a simple idempotent read tool.

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 both parameters (limit, cursor) are fully documented in the schema, so the baseline is 3. The description says nothing about pagination or page-size behavior, adding no semantics 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 ('List every CodeAtlas service') and enumerates the returned fields, which is unusually informative. It does not explicitly distinguish itself from codeatlas_get_service or codeatlas_search_services, though 'every' implies unfiltered enumeration.

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 only implied: 'List every' suggests using this for full enumeration rather than for filtered search or single-item lookup, but no alternative is named and no when-not condition is given. An agent must infer the boundary against codeatlas_search_services.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=true). The description adds genuinely new operational context: it dispatches an email outside the system and requires an OAuth Bearer token with scope api:write, including a link to the auth docs. It stops short of describing failure modes or rate limits, so it is strong but not exhaustive.

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?

Three sentences, front-loaded with the action and recipient, then the auth requirement, then the precondition. No sentence is redundant and nothing is buried.

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 write tool with no output schema, the definition covers purpose, dispatch mechanism, auth scope, and invocation preconditions, which is most of what an agent needs. Remaining gaps are secondary: no mention of error behavior or what a successful call returns to the caller.

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 carries full parameter semantics and a 3 is the baseline. The description only adds the framing that 'name' and 'email' belong to the person on whose behalf the agent acts, which is mild added value and not enough to raise the score.

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 ('Submit a first-conversation request to CodeAtlas') and clarifies the mechanism ('Sends an email to the CodeAtlas team'). The siblings are all read-only service lookups, so the write-oriented contact intent is unmistakably distinct 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, gating precondition: 'Only call this after the person asked you to contact CodeAtlas and gave you their name and email.' That is a clear when-to-use rule with an implicit when-not. It does not reference the sibling tools, but no plausible confusion exists with service lookups, so the omission is minor.

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, non-destructive and closed-world, so the safety profile is covered. The description adds two genuinely new behavioral facts: queries are accepted in Portuguese or English, and an empty query returns the full set. It stops short of describing result format or pagination.

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 short sentences, no filler, with the core capability stated first and the empty-query edge case immediately after. Every clause carries information.

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-only search this is nearly sufficient, and annotations carry the safety profile. Since no output schema exists, a brief note on what a match returns (service name, capability match, ordering) would have closed the remaining gap.

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 goes beyond the schema by clarifying that the query string may be written in Portuguese or English and that an empty string is a legal, meaningful value even though the parameter is required. That is real added semantics.

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+resource ('Search CodeAtlas services') and the axis of search ('by business challenge or capability'), which is more than a restatement of the name. It does not, however, distinguish itself from the sibling codeatlas_list_services, even though the 'empty query returns all services' note reveals the two overlap.

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 only implied: the empty-query behavior hints at when this can substitute for listing all services, but the description never states when to search versus call codeatlas_list_services or codeatlas_get_service. No prerequisites or exclusions are given.

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