DevRel Directory

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses methodology (USD-only salary blending, remote-friendly classification reading remote-prefixed locations), output fields (n, smallSample, canonicalUrl, methodologyUrl), and interpretation cautions. This is exceptionally transparent.

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 long and dense, but every clause adds a specific metric or caveat. It is front-loaded with the core purpose and then elaborates. Slightly run-on in structure but each sentence earns its place given the complexity.

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 no-parameter, no-output-schema tool, the description covers all apparent behaviors: what statistics are included, how salary is computed, how to interpret sample sizes, and where to find underlying methodology. It is complete without needing an output schema.

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 schema has zero parameters with 100% coverage, so the description appropriately focuses on output semantics and data interpretation rather than parameter details. Baseline for 0 params is 4, and the description adds value by explaining the meaning of returned fields.

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 opens with 'Aggregate statistics across devrel.directory in one call' and lists specific metrics (listing counts, job count, salary stats), clearly distinguishing it from sibling tools like get_listing or list_jobs that return individual items. It is a specific verb+resource with detailed scope.

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 phrase 'in one call' implies this is a one-stop alternative to multiple list calls, and there is explicit guidance on how to use salary figures ('always cite n', 'qualify' small samples). However, it does not explicitly state when not to use this tool or name alternatives, so it falls 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?

With no annotations provided, the description carries the full burden. It thoroughly discloses what the tool returns (all listed components) and even the error behavior for unknown slugs, leaving no surprises for the agent.

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 a single dense sentence that is front-loaded with the core action, but it is long with many comma-separated details. All information is relevant, so it earns a 4 rather than a 3 for wordiness, though it sacrifices brevity.

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 there is no output schema, the description fully compensates by detailing every category of returned data and the error case. For a one-parameter tool this is complete and unambiguous.

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 input schema already covers the slug parameter with a description (including 'as returned by search_directory') at 100% coverage. The tool description adds no new parameter-specific meaning beyond what the schema provides, 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?

The description begins with a specific verb and resource: 'Get the full detail for one directory listing by its slug.' It goes on to enumerate exactly what is included (maintenance signals, similar listings, jobs/events), clearly distinguishing it from sibling tools like search_directory or directory_stats.

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 context is clear: this is for retrieving full detail by slug, and it even cross-references search_directory as the source for slugs. However, it doesn't explicitly state when not to use it or name alternative tools, stopping 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?

With no annotations provided, the description carries the full burden. It discloses the default behavior (upcoming only), the effect of the two boolean flags, and the presence of external url and canonicalUrl in results. However, it does not mention pagination, potential rate limits, or explicitly state that it is a read-only operation.

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 two sentences with the purpose front-loaded. It efficiently covers the main functionality, filter options, and key output fields without any redundant or verbose wording.

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 no annotations and no output schema, the description covers the tool's purpose, filter behavior, and key output fields (url and canonicalUrl). It lacks full return structure details and any caveats, but is reasonably complete for a simple listing 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 coverage is 100%, so each parameter already has a description. The tool description adds a bit of context by showing how the flags interact (e.g., setting upcomingOnly to false includes past events) but does not introduce substantial new 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?

The description clearly states the tool lists DevRel events and conferences with CFP deadlines, distinguishing it from sibling tools like list_jobs and search_directory. The verb 'List' and specific resource 'DevRel events' make the purpose unambiguous.

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 context is implied through the explanation of default filters and how to change them, but there is no explicit guidance on when to choose this tool over alternatives like search_directory or get_listing, nor any exclusion criteria.

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?

With no annotations, the description carries the behavioral burden and delivers: it specifies that only 'currently open' jobs are returned, clarifies salary floor logic (compared against highest bound, posting's currency, no-pay roles never qualify), notes the default for omitted employment type, and mentions output URLs. This is substantive transparency, though it omits pagination/ordering details.

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 compact and front-loaded with the core purpose, then efficiently explains filters and output. No filler, every sentence earns 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?

Without an output schema, the description covers query semantics and result fields (URLs). It does not mention pagination, ordering, result limits, or error cases, but for a listing tool the provided context is largely sufficient. Would be a 5 with pagination/ordering noted.

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 schema already documents each parameter thoroughly. The description adds contextual reassurances ('same semantics as the site's jobs page', salary fields passed through) but does not introduce new meaning beyond the schema. This matches the baseline for high schema coverage.

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 uses a specific verb ('List') and a specific resource ('currently open DevRel job postings'), and enumerates the filters and output fields. This clearly distinguishes it from sibling tools like list_events (events) and search_directory (general directory 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?

It states that filters match the site's jobs page semantics, which implies when to use it (for job listings) and provides clear context. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of an explicit when/when-not/alternatives guide.

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?

With no annotations, the description carries the behavioral burden. It discloses that query matches against name, description, and tags, and that results include external url and canonicalUrl. However, it does not mention pagination, result limits, or any potential rate limits, leaving some behavioral aspects undisclosed.

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 long, front-loaded with the core purpose, and every sentence adds value. There is no redundant or filler 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?

For a two-optional-parameter search tool with no output schema, the description covers the essential functionality, filter behavior, and output fields. It lacks explicit pagination or error handling details, but the overall scope is well-covered given the tool's simplicity.

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 schema description coverage is 100% for both parameters. The description essentially restates what the schema already says (free-text substring matching and exact category filter), adding little new semantic information. Baseline 3 is appropriate as 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?

The description clearly states the tool searches devrel.directory listings and enumerates the types of entities (tools, communities, newsletters, podcasts, agencies). The verb 'search' and resource are specific, and it is distinct from sibling tools like search_docs or list_events by explicitly naming the directory domain.

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 clear context for when to use this tool—when searching directory listings—and explains the two filtering modes (free-text and category). However, it does not explicitly specify when not to use it or mention alternatives, though the scope is well-defined relative to sibling tools.

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?

With no annotations, the description must carry the burden of behavioral disclosure. It states that results include absolute URLs and that event results deep-link to specific events, which goes beyond the schema. It implies a read-only operation by describing a search, but does not mention auth, rate limits, or failure modes, though these are less critical for a simple search.

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 two sentences long, front-loaded with the core purpose and followed by return-value details. Every clause adds information; no filler or repetition of schema fields.

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 a single parameter and no output schema, so the description must cover both semantics and returns. It explains the search scope and the nature of results (URLs, event deep-links), making it reasonably complete for the tool's simplicity. It stops short of describing result fields or limits, but this is acceptable given the low complexity.

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 schema already defines 'query' as the search query, and the description adds that the query searches across the unified index including specific content types. This clarifies what the query targets, adding value beyond the schema's minimal description. However, it doesn't provide query syntax or filter options.

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 searches a unified index of multiple content types (docs, blog posts, directory listings, jobs, events). The verb 'Search' and specific resource make it distinct from sibling tools like search_directory, which likely focuses on directories only.

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 clear context: this is a unified search across all content categories. It implies use when you need cross-type search results, but does not explicitly state when not to use it or name alternatives. The coverage of multiple content types is a strong contextual signal.

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