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 that the tool returns data for analysis (read-only behavior) and outlines the expected workflow, but doesn't mention potential limitations like rate limits, authentication needs, or error conditions. The description adds useful context about the analysis process but lacks comprehensive behavioral 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 well-structured with clear sections: purpose statement, returns explanation, args documentation, and example workflow. Every sentence serves a purpose, though the workflow example is somewhat lengthy. The information is front-loaded with the core purpose stated first.

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 the tool's moderate complexity (2 parameters, analysis preparation purpose) and the presence of an output schema, the description is reasonably complete. It explains the tool's role in the workflow, documents parameters, and describes what the agent should do with the results. The output schema likely covers return structure details, so the description appropriately focuses on usage 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?

Schema description coverage is 0%, so the description must compensate. It explains both parameters: 'poem_id' as 'Poem identifier (ID or title)' and 'max_suggestions' as 'Maximum number of theme suggestions requested'. This adds meaningful semantics beyond the bare schema, though it doesn't provide format details or constraints for 'poem_id'.

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 with specific verbs ('prepare poem and theme data for analysis') and resources ('poem content and available themes'). It distinguishes from siblings like 'get_poem' by emphasizing the analysis preparation aspect and explicitly mentions the agent's role in analyzing themes, which sets it apart from simple data retrieval tools.

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 on when to use this tool: to prepare data for theme analysis, with an example workflow showing it's the first step before using 'link_poem_to_nexus'. It doesn't explicitly state when NOT to use it or name alternatives, but the workflow implies it's for analysis preparation rather than direct tagging or retrieval.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool 'Returns: List of matching poems' but lacks critical details: whether this is a read-only operation (implied by 'Find' but not explicit), pagination behavior (only 'limit' is mentioned), error handling, or performance characteristics like rate limits. For a tool with 4 parameters and no annotation coverage, this is insufficient.

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 and well-structured: it starts with a clear purpose statement, followed by an 'Args:' section listing parameters with brief semantics, and ends with a 'Returns:' statement. Each sentence earns its place, though the 'Args:' and 'Returns:' labels add minor redundancy. It could be slightly more front-loaded by integrating parameter hints into the opening sentence.

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 the tool's moderate complexity (4 parameters, no annotations, but with an output schema), the description is partially complete. The output schema exists, so the description doesn't need to detail return values. However, it lacks behavioral context (e.g., safety, performance) and usage guidelines compared to siblings. With 0% schema description coverage, the parameter explanations help but don't fully compensate for missing behavioral transparency.

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 0%, so the description must compensate. It lists all 4 parameters with brief explanations: 'tags: List of tags to match', 'match_mode: "all" (poems must have all tags) or "any" (at least one tag)', 'states: Optional filter by states', and 'limit: Maximum number of results'. This adds meaning beyond the bare schema (e.g., clarifying match_mode options), but it doesn't explain parameter interactions, constraints (e.g., tag format), or default behaviors beyond what's in 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's purpose: 'Find poems by tags' specifies both the verb ('Find') and resource ('poems'), with the mechanism ('by tags') providing additional specificity. It distinguishes from siblings like 'list_poems_by_state' (which filters by state rather than tags) and 'search_poems' (which likely uses different search criteria). However, it doesn't explicitly contrast with all siblings, preventing a perfect score.

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 no guidance on when to use this tool versus alternatives. It doesn't mention siblings like 'list_poems_by_state' (for state-based filtering) or 'search_poems' (which might support broader search capabilities), nor does it specify prerequisites or exclusions. The only implied usage is tag-based poem retrieval, but this is already covered in purpose clarity.

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?

No annotations are provided, so the description carries the full burden. It describes the return structure ('complete registry with all nexus entries, organized by category') and includes an example, but lacks details on potential limitations like rate limits, authentication needs, or error handling. It does not contradict any 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?

The description is front-loaded with the core purpose, followed by usage guidance, return details, and an example. It is appropriately sized, but the example could be slightly more concise. Most sentences add value, with minimal 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?

Given the tool's low complexity (0 parameters, simple read operation), the description provides complete context: purpose, usage, return structure, and an example. The presence of an output schema means return values need not be detailed, and the description adequately covers what's needed for a straightforward registry retrieval 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?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately focuses on output and usage without redundant parameter details, earning a baseline score of 4 for effectively handling a parameter-less tool.

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 verb ('Get') and resource ('all nexuses'), specifies what nexuses are ('themes/motifs/forms'), and distinguishes from siblings by indicating this retrieves the complete registry for discovery purposes, unlike tools like 'find_nexuses_for_poem' or 'link_poem_to_nexus' that focus on specific poems or tagging.

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 explicitly states when to use it ('Use this to discover available themes, motifs, and forms for tagging poems'), providing clear context. However, it does not specify when not to use it or name alternatives among siblings, such as 'find_nexuses_for_poem' for poem-specific queries.

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?

No annotations are provided, so the description carries the full burden. It mentions the return type 'CatalogStats with counts, metrics, and health information', which adds some behavioral context about output structure. However, it doesn't disclose critical traits like whether this is a read-only operation, performance implications, or error conditions, which are important for a tool with no annotation coverage.

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 with two sentences: one stating the purpose and another detailing the return structure. It's front-loaded with the main action and avoids redundancy, though it could be slightly more structured for clarity.

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 the tool has 0 parameters, an output schema exists (which covers return values), and no annotations, the description is minimally adequate. It states the purpose and return type, but for a tool in a context with many siblings, it lacks differentiation and behavioral details that would make it more complete for agent use.

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 tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter information, and it doesn't introduce any confusion. Baseline is 4 for zero parameters, as it appropriately avoids unnecessary details.

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 states the tool 'Get catalog statistics' which is a clear verb+resource combination, but it's vague about what 'catalog statistics' specifically entails compared to siblings like 'get_server_info' or 'sync_catalog'. It doesn't distinguish itself from potential overlaps with other tools that might provide statistical or health information.

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?

No guidance is provided on when to use this tool versus alternatives. With siblings like 'get_server_info' and 'sync_catalog' that might offer related information, the description lacks any context about use cases, prerequisites, or exclusions, leaving the agent to infer usage.

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 of behavioral disclosure. It mentions that the tool returns 'Poem object or None if not found', which adds some context on error handling. However, it lacks details on permissions, rate limits, side effects, or what the 'Poem object' entails (e.g., structure, fields). For a read operation with zero annotation coverage, this is minimal but not 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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by structured sections for args and returns. Each sentence adds value, with no redundant information. It could be slightly more concise by integrating the sections, but overall it's efficient and well-organized.

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 the tool's moderate complexity (2 parameters, no annotations, but has an output schema), the description is partially complete. The output schema likely covers return values, so the description doesn't need to detail the 'Poem object'. However, it lacks usage guidelines and full behavioral context, making it adequate but with clear gaps for effective tool selection.

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 0%, so the description must compensate. It explains that 'identifier' can be 'Poem ID or exact title', adding meaning beyond the schema's string type. For 'include_content', it clarifies 'Whether to include full poem text', which is useful. However, it doesn't cover nuances like case-sensitivity for titles or default behavior, leaving some gaps given the low 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 clearly states the tool's purpose: 'Get a poem by ID or title.' It specifies the verb ('Get') and resource ('poem'), and distinguishes it from siblings like 'search_poems' or 'list_poems_by_state' by focusing on retrieval via specific identifier. However, it doesn't explicitly differentiate from 'find_poems_by_tag' or 'get_poems_for_enrichment', which might also retrieve poems, so it's not fully sibling-distinctive.

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 no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like preferring 'search_poems' for fuzzy matching, 'list_poems_by_state' for filtered lists, or 'find_poems_by_tag' for tag-based retrieval. There's no context on prerequisites or exclusions, leaving the agent to infer usage from the purpose alone.

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 and does well: it explains the tool returns poems for agent analysis, specifies the return structure (poems, available_themes, instructions), and mentions the default behavior (max_poems=50). However, it doesn't cover potential rate limits, authentication needs, or error conditions, leaving some behavioral aspects unspecified.

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 well-structured and front-loaded: the first sentence states the purpose, followed by key details (returns, args, returns), and ends with a practical example workflow. Every sentence adds value, with no redundancy or fluff, making it efficient for agent comprehension.

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 the tool's complexity (batch retrieval for analysis), no annotations, and an output schema (which covers return values), the description is complete: it explains purpose, usage, parameters, return structure, and provides an example workflow. This adequately guides the agent without needing to repeat output schema details.

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 0%, so the description must compensate fully. It does: it explains poem_ids as 'List of poem IDs (None = all untagged/lightly-tagged poems)' and max_poems as 'Maximum poems to return (default 50)', adding crucial meaning beyond the bare schema. The example workflow further 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: 'Get batch of poems needing theme enrichment for agent analysis.' It specifies the verb ('Get'), resource ('poems'), and qualifying condition ('needing theme enrichment'), distinguishing it from siblings like get_poem (single poem) or find_poems_by_tag (already tagged).

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 explicitly states when to use this tool: for poems with 'minimal or no tags' that need theme analysis by the agent. It provides an example workflow showing this tool as step 1, followed by agent analysis and linking with link_poem_to_nexus, clearly differentiating it from sibling tools that retrieve already-tagged poems or manage states.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the return type ('Dictionary with server metadata'), which adds some value, but fails to cover critical aspects like whether this is a read-only operation, authentication requirements, rate limits, or error conditions. For a tool with zero annotation coverage, this is a significant gap.

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 with two sentences: the first states the purpose, and the second specifies the return type. It's front-loaded and wastes no words, though the second sentence could be slightly more integrated for perfect structure.

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 the tool's simplicity (0 parameters, output schema exists), the description is minimally adequate. It explains what the tool does and the return format, but with no annotations and siblings that might overlap, it lacks context on behavioral traits and usage distinctions, leaving room for improvement.

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 tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter semantics, and it appropriately avoids discussing parameters, earning a high baseline score for not introducing unnecessary information.

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 with a specific verb ('Get') and resource ('server information and status'), making it immediately understandable. However, it doesn't differentiate this from sibling tools like 'get_catalog_stats' or 'sync_catalog' that might also provide server-related information, preventing a perfect score.

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 no guidance on when to use this tool versus alternatives. With siblings like 'get_catalog_stats' that might overlap in functionality, there's no explicit or implied context for choosing this tool, leaving the agent without usage direction.

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 of behavioral disclosure. It clearly describes what the tool returns (poem data, dimensions, instructions) and the grading workflow, but doesn't mention potential limitations like error handling, authentication needs, or rate limits. The behavioral information is adequate but not comprehensive.

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 well-structured with clear sections (purpose, dimensions list, args, returns, workflow) but could be more concise. The 8 dimensions list and detailed example workflow are valuable but make it somewhat lengthy. Every sentence serves a purpose, but some information could be more efficiently presented.

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 the tool's complexity (preparing grading materials with 8 quality dimensions) and the presence of an output schema, the description provides good context. It explains the grading dimensions, parameters, return structure, and workflow. The output schema means it doesn't need to detail return values, but it still provides helpful context about the grading process.

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 0% schema description coverage, the description must compensate for the schema's lack of parameter documentation. It explains both parameters: 'poem_id' as 'Poem identifier (ID or title)' and 'dimensions' as 'Optional list of specific dimensions to grade (default: all 8)'. It also lists the 8 possible dimensions, providing essential context missing from 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's purpose with specific verbs ('prepare poem and quality rubric for grading') and resources ('poem content and quality dimension descriptions'). It distinguishes itself from sibling tools like 'get_poem' by emphasizing the grading preparation aspect rather than just retrieval.

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 guidance on when to use this tool versus alternatives through the example workflow, which shows it's for preparing grading materials. It implicitly distinguishes from siblings like 'get_poem' (which just retrieves poems) and 'search_poems' (which searches without grading context).

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 and does well by disclosing key behavioral traits: it 'safely updates' and 'preserves all other fields', 'creates a backup before modification', and 'automatically resyncs catalog after update'. This covers safety, mutation effects, and side-effects, though it could mention permissions or error handling.

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 and front-loaded: the first sentence states the purpose, followed by behavioral details, then parameter explanations, return value, and an example. Every sentence adds value with zero waste, making it easy to scan and understand.

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 3 parameters with 0% schema coverage, no annotations, and an output schema (implied by 'Returns' statement), the description is mostly complete. It covers purpose, behavior, parameters, and returns, but could improve by mentioning error cases or linking to sibling tools for context, though the output schema reduces the need for return value details.

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 0%, so the description must compensate. It adds meaning by explaining 'poem_id' as 'Poem identifier (ID or title)', 'nexus_name' with examples ('Water-Liquid', 'Childhood'), and 'nexus_type' with default and allowed values ('theme/motif/form'). This clarifies beyond the bare schema, though it doesn't detail format constraints for 'poem_id'.

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 specific action ('Link a poem to a nexus by adding the nexus's canonical tag'), identifies the resource ('poem'), and distinguishes it from sibling tools like 'sync_nexus_tags' or 'find_nexuses_for_poem' by focusing on the linking operation rather than synchronization or querying.

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 implies usage through the example (linking a poem to a theme) but does not explicitly state when to use this tool versus alternatives like 'sync_nexus_tags' or 'move_poem_to_state'. It provides context but lacks explicit guidance on exclusions or prerequisites.

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?

No annotations are provided, so the description carries full burden. It mentions the tool 'List poems' but doesn't disclose behavioral traits like whether this is a read-only operation, if it requires authentication, rate limits, pagination behavior, or what happens with invalid states. The description is minimal and lacks critical operational context.

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 efficiently structured with a clear purpose statement followed by organized sections for Args and Returns. Every sentence adds value: the first states the purpose, and the subsequent lines explain parameters and return value without redundancy. It's appropriately sized and front-loaded.

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 3 parameters with 0% schema coverage and no annotations, the description partially compensates by explaining parameter semantics. However, it lacks behavioral transparency details (e.g., read-only nature, error handling). The output schema exists, so return values don't need explanation, but overall completeness is moderate due to missing operational 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?

Schema description coverage is 0%, so the description must compensate. It provides semantic meaning for all three parameters: 'state' (filter by state with examples), 'sort_by' (field to sort by with options), and 'limit' (maximum results). This adds valuable context beyond the bare schema, though it doesn't specify format details like state enum values or limit ranges.

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: 'List poems in a specific state.' It specifies the verb ('List') and resource ('poems') with a filtering condition ('in a specific state'). However, it doesn't explicitly differentiate from siblings like 'find_poems_by_tag' or 'search_poems' beyond the state filtering aspect.

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 no guidance on when to use this tool versus alternatives. With siblings like 'find_poems_by_tag', 'search_poems', and 'get_poems_for_enrichment', there's no indication of when state-based filtering is preferred over other filtering methods or what prerequisites might exist.

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 of behavioral disclosure. It effectively describes key behaviors: it moves files between directories, updates frontmatter, and handles backup files automatically. However, it lacks details on error handling, permissions needed, or rate limits, which would be beneficial for a mutation tool.

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 well-structured with a clear purpose statement, bullet points for args and returns, and a practical example. It is appropriately sized, though the example could be slightly more concise. Every sentence adds value, with no redundant 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?

Given the tool's complexity (mutation with file operations), no annotations, and an output schema present, the description is mostly complete. It covers purpose, parameters, and example usage, but could improve by addressing error cases or integration with sibling tools. The output schema reduces the need to detail return values.

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 0%, so the description must compensate fully. It clearly explains both parameters: 'poem_id' as 'Poem identifier (ID or title)' and 'new_state' as 'Target state (completed, fledgeling, still_cooking, etc.)', including examples of state values. This adds essential meaning beyond the bare 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 specific action ('Move a poem to a different state directory and update frontmatter'), identifies the resource ('poem file'), and distinguishes it from siblings by focusing on state transitions rather than searching, linking, or grading operations. It explicitly mentions moving between specific state directories like 'Completed' and 'Fledgelings'.

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 implies usage context through the example ('Promote a poem to completed') and mentions state directories, but it does not explicitly state when to use this tool versus alternatives like 'list_poems_by_state' or 'get_poem'. No exclusions or prerequisites are provided, leaving some ambiguity about appropriate scenarios.

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 full burden but offers minimal behavioral insight. It mentions the return type ('SearchResult') but doesn't disclose pagination, rate limits, authentication needs, error conditions, or whether this is a read-only operation. The description is functional but lacks critical operational context.

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 efficiently structured with a clear purpose statement followed by well-organized Args and Returns sections. Every sentence adds value—no fluff or repetition. It's appropriately sized for a 6-parameter search tool.

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 6 parameters with 0% schema coverage and no annotations, the description does a decent job explaining parameters and mentions the return type. However, for a search tool with many sibling alternatives and no behavioral annotations, it should provide more guidance on usage context and operational limits to be fully 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 description coverage is 0%, but the description compensates well by explaining all 6 parameters with clear semantics: what each filters, examples for states/forms, tag logic ('must have all'), and purpose of include_content. It adds meaningful context beyond the bare schema types, though some details like exact format expectations remain unspecified.

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 as 'Search for poems matching criteria,' which is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'find_poems_by_tag' or 'list_poems_by_state,' which appear to offer more specialized search capabilities.

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 no guidance on when to use this tool versus alternatives like 'find_poems_by_tag' or 'list_poems_by_state.' It mentions criteria but doesn't explain trade-offs, prerequisites, or comparative advantages with 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 provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's action (scanning files, building indices) and prerequisite nature, though it lacks details on error handling, performance implications, or side effects beyond the sync operation. No contradictions exist.

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 front-loaded with the core purpose, followed by usage guidelines and parameter/return details in a structured format. Every sentence adds value without redundancy, making it efficient and easy to parse.

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 the tool's complexity (prerequisite sync operation), no annotations, and an output schema (implied by 'Returns'), the description is mostly complete. It covers purpose, usage, parameters, and returns, but could benefit from more behavioral context like error scenarios or performance notes.

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 0%, so the description must compensate. It explains the single parameter 'force_rescan' with its effect ('rescan all files even if already loaded'), adding meaningful context beyond the schema's type and default. However, it doesn't cover edge cases or examples.

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 specific action ('Synchronize catalog from filesystem') and resource ('catalog'), distinguishing it from sibling tools like 'get_catalog_stats' or 'sync_nexus_tags'. It explicitly mentions scanning markdown files in the catalog/ directory and building in-memory indices, providing a precise operational 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 description explicitly states 'This should be called before using other catalog tools,' providing clear when-to-use guidance. It distinguishes this tool as a prerequisite for operations like 'find_poems_by_tag' or 'search_poems,' with no misleading exclusions.

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 full burden for behavioral disclosure. It describes the core synchronization behavior and mentions conflict detection ('any conflicts found'), but doesn't address important behavioral aspects like whether this operation is idempotent, what permissions are required, whether it modifies the original poem file, or what happens with malformed wikilinks. It provides basic operational transparency but misses key implementation 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 well-structured and appropriately sized. It begins with a clear purpose statement, follows with parameter explanations, return value description, and a practical example. Every sentence adds value, with no redundant information. The example is particularly helpful for understanding tool usage without being verbose.

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 the tool's moderate complexity (bidirectional synchronization with conflict detection), no annotations, and the presence of an output schema (which handles return value documentation), the description provides good contextual coverage. It explains the synchronization logic, parameters, and includes a helpful example. The main gap is lack of behavioral details about file modification, permissions, and error handling that would be important for a mutation 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?

With 0% schema description coverage, the description must fully compensate for the lack of schema documentation. It successfully explains both parameters: 'poem_id' as 'Poem identifier (ID or title)' and 'direction' with its three specific values and default of 'both'. The description adds meaningful context about what these parameters control, though it could provide more detail about poem_id format expectations.

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 specific action ('synchronize'), target resource ('Nexus links in poem body with frontmatter tags'), and mechanism ('analyzes the poem's content for [[Nexus Name]] wikilinks'). It distinguishes this tool from siblings like 'link_poem_to_nexus' (which creates individual links) and 'sync_catalog' (which likely operates at catalog level rather than poem-level synchronization).

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 about when to use this tool ('syncs them with the frontmatter tags field') and mentions three specific direction options, but doesn't explicitly state when to choose each direction or when to use alternatives like 'link_poem_to_nexus' for manual linking versus automated synchronization. It gives operational context but lacks comparative guidance against sibling tools.

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