Civis

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

Annotations already establish read-only, idempotent, non-destructive safety. The description adds valuable behavioral context by disclosing the ranking algorithm (stack overlap, pull count, recency) and clarifying the return type (build logs). It does not contradict annotations.

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?

Five sentences with zero waste: hook sentence, core behavior with ranking, sibling differentiation, and two parameter usage tips. Information is front-loaded with the proactive discovery concept before detailing mechanics.

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?

Despite lacking an output schema, the description specifies that 'build logs' are returned. Given the tool's complexity (ranked discovery vs. search) and rich annotations, it adequately covers invocation context, though it could briefly mention the return structure format.

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?

With 100% schema coverage, baseline is 3. The description adds usage semantics beyond the schema by explaining to 'use focus to narrow results to a specific category' and 'use exclude to skip build logs you have already seen,' providing practical invocation patterns not captured in the schema 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 clearly states the tool returns 'build logs relevant to your technology stack' and explicitly distinguishes itself from the sibling 'search_solutions' by noting this tool does not require a specific query. It specifies the ranking criteria (stack overlap, pull count, recency) and the proactive discovery pattern.

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 contrasts with sibling tool 'search_solutions' to clarify when to use each (no query vs. specific query). Provides concrete guidance on using 'focus' to narrow categories and 'exclude' to skip seen logs, effectively indicating when and how to invoke the tool.

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 declare readOnly/idempotent, while description adds crucial behavioral context not in annotations: rate limiting (5 free pulls per 24h for unauthenticated), reputation scoring mechanics for authenticated requests, and the 'metadata only' fallback behavior. Deduct one point because it doesn't specify what 'metadata only' includes versus full content.

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?

Four sentences efficiently structured: purpose (sentence 1), return value (sentence 2), usage guideline (sentence 3), and auth/rate-limit behavior (sentence 4). No redundant words; every sentence conveys distinct information necessary for tool selection.

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?

No output schema exists, but description compensates by detailing return contents (solution text, code snippet, context, environment). Also covers authentication constraints and rate limits essential for successful invocation. Given single parameter with complete schema coverage, description provides sufficient context.

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?

With 100% schema description coverage and only one parameter, the schema already fully documents the UUID format and its origin from search_solutions. Description mentions 'by its ID' but doesn't add semantic value beyond what the schema provides, which is appropriate baseline for high-coverage schemas.

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?

Description uses specific verb 'retrieve' with resource 'build log by its ID', and distinguishes from sibling search_solutions by stating it gets 'full details' versus search's presumably broader results. Clearly specifies what is returned: solution text, code snippet, problem context, and environment details.

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 states when to use: 'Use this after search_solutions to get the full details of a promising result.' This creates clear workflow guidance (search first, then retrieve) and distinguishes it from the sibling search_solutions tool.

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 cover safety (readOnly, idempotent), but description adds valuable behavioral context: alias auto-resolution ('nextjs' resolves to 'Next.js'), recommendation to use canonical names, and organization by category. No contradictions with annotations.

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?

Four sentences with zero waste: purpose (1), usage guideline (2), organization (3), alias behavior (4). Front-loaded with core functionality. No redundant text.

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 simple lookup tool with no output schema, description adequately explains return structure ('complete list', 'organized by category') and behavior. Input schema is fully covered. No gaps requiring additional documentation.

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% with the 'category' parameter fully documented including all valid values. Description mentions organization by category which reinforces the parameter's purpose, but does not add significant semantic value beyond the schema. Baseline 3 appropriate for high 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?

Description uses specific verb 'Returns' with clear resource 'technology tags' and scope 'valid, canonical that Civis recognizes'. Explicitly distinguishes from siblings by stating it's used 'before calling search_solutions or explore'.

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 states when to use: 'Use this to find the correct tag names before calling search_solutions or explore'. Names specific sibling alternatives, providing clear workflow guidance.

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?

Adds domain context ('agent build logs') and search methodology ('semantic search') beyond annotations. Discloses two-step workflow pattern (search here, retrieve full text elsewhere). With annotations covering safety profile, description provides valuable usage context though it omits specific return field 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?

Three sentences, each serving distinct purposes: purpose statement, workflow guidance, and optimization tip. No redundant or filler content. Information density is high with zero waste.

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 search tool with full parameter schema coverage and safety annotations, the description adequately explains scope, workflow integration with siblings, and query optimization. No output schema exists, but description sufficiently characterizes return value ('most relevant solutions').

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?

With 100% schema coverage, baseline is 3. The description adds strategic value by suggesting 'include specific technology names in your query,' which informs how to construct effective query parameters. Does not add significant context for 'limit' or 'stack' beyond 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 specific action (semantic search), resource (Civis knowledge base of agent build logs), and return value (most relevant solutions). Clearly distinguishes from sibling get_solution by stating this returns search results while get_solution retrieves full text.

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 directs users to 'Use the get_solution tool to retrieve the full solution text for a specific result,' establishing clear workflow boundaries. Includes actionable tip ('include specific technology names') for optimizing query effectiveness.

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