moja.work portfolio

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

No annotations provided; description only mentions returning 'full glossary entry (plain text)'. This is adequate for a simple read operation, but lacks any mention of error cases, permissions, or side effects.

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?

Single sentence that front-loads the action and resource. Every word contributes to clarity; no unnecessary 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 simple get-by-id tool returning plain text, the description covers the main purpose. Could be more explicit about what 'full glossary entry' includes (e.g., definition, examples), but the output schema is absent and not required. Adequate for the task.

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 clear descriptions for both parameters. The description adds context by specifying 'plain text' and giving example IDs ('angular, typescript, git'), but this is marginal value 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?

Description clearly states the verb 'Get', the resource 'full glossary entry', and the method 'by its id'. It distinguishes from sibling tools like list_buzzwords (which returns multiple) and search_buzzwords (which searches by term).

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?

Implies usage when you have a specific buzzword ID, but does not provide explicit guidance on when to use alternative tools (e.g., list_buzzwords or search_buzzwords) or any prerequisites. No exclusion criteria mentioned.

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 does not disclose any behavioral traits beyond the listed fields, such as whether it requires authentication, rate limits, or side effects. It only mentions 'public' details, implying no auth, but not explicitly.

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 sentence, no fluff, clearly conveys the purpose. Every word is earned.

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, so description should explain return format. It lists fields but not structure or whether it returns a vCard file or object. Mention of vCard is ambiguous.

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 no parameters (0 parameters), so parameter semantics are trivially covered. Baseline for 0 params is 4, and the description adds no extra parameter info 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 verb 'Get' and the resource 'public contact details / vCard', and lists specific fields (name, email, phone, etc.). It distinguishes itself from sibling tools like get_buzzword or get_docs.

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 on when to use this tool compared to alternatives or when not to use it. The description does not mention context, prerequisites, or 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?

No annotations provided, so description carries full burden. It states 'Get' indicating a read operation and adds 'Can be large' as a size warning. This adequately discloses the non-destructive, potentially large nature of the 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?

Two sentences concisely convey purpose and a caveat ('Can be large'), with no superfluous content. Efficient 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 no output schema, the description hints at output format via 'LLM-friendly code documentation (Compodoc llm-md export)', implying Markdown. It lacks explicit output structure but is adequate for a simple retrieval tool with a single parameter.

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 covers all parameters (100%). The description adds meaningful context: 'LLM-friendly code documentation (Compodoc llm-md export)' and 'for one project of the monorepo', enhancing understanding 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 verb 'Get' and resource 'LLM-friendly code documentation (Compodoc llm-md export) for one project of the monorepo'. It distinguishes from sibling tools like list_docs (lists documentation sets) and other get_* 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 implies usage for retrieving documentation for a specific project but does not explicitly state when to use it versus alternatives or provide exclusions. With multiple sibling get tools, some guidance would help.

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 provided. The description explains the return format (list of sections with fields) and optional filtering, providing sufficient behavioral context for a read 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?

Single sentence, front-loaded with the purpose, no unnecessary words. Efficient.

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?

Complete enough for a simple read tool with 2 parameters and 100% schema coverage. Could mention error cases, but not critical.

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%, baseline 3. The description adds value by explaining that anker returns a single section with examples, exceeding 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 retrieves 'The Chronicle of the Three Realms' as an ordered list of sections, distinguishing it from sibling tools like get_buzzword or get_timeline.

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 implicitly indicates usage: to get the epic retelling. It mentions optional anker for a single section, but does not explicitly state when to use this over siblings; however, the resource is unique.

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, but the description discloses behavior like the structured output format, the separate language texts, and the news section's delegation to another tool, adding significant context beyond what the schema shows.

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 detailed but not overly verbose, placing the main purpose upfront with useful specifics. A few extra clarifications could be trimmed, but it remains efficient.

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 thoroughly covers output structure, language handling, and the option filter. Without an output schema, it compensates well, though it could briefly clarify the 'url' field's 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?

The schema describes both parameters, but the description adds meaning by explaining the 'anker' values and the structured output. Even with full schema coverage, it enriches semantics with concrete anchor names and structural 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 clearly states the tool returns the start page of moja.work as an ordered list of sections and identifies the specific named sections, so its purpose is unmistakable and distinct from siblings.

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 indicates the optional 'anker' parameter to return one section but does not explicitly say when to use this tool over siblings or mention exclusions. It implies usage but does not offer routing 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?

With no annotations, the description carries the full burden. It discloses the return format (Markdown page with build-time figures filled in), the additional list of available pages, and the default overview behavior. However, it does not explicitly state read-only safety, error behavior, or any side effects, which would be expected for an unannotated 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 moderately sized and front-loads the purpose, then adds return details and default behavior. The opening clause 'Plattform pages — moja.work described as what it is' is slightly awkward, but most sentences contribute functional value.

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 low-complexity tool with 2 optional params, no annotations, and no output schema, the description covers the return value (Markdown page, filled figures, available pages list) and the default behavior. It does not address errors or edge cases, but it is sufficiently complete for a simple read-oriented get 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%, so the schema already documents `lang` and `page` fully. The description adds only that the default page is the overview, which aligns with the schema's 'Default: the first page.' It does not introduce new parameter 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 names a specific verb-resource pairing ('Get the Plattform pages') and details what the pages contain (monorepo documentation, UI library, apps, npm packages, architecture). This helps distinguish it from siblings like get_docs or get_project, though it stops short of an explicit contrast statement.

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 when-to-use guidance or alternative tool names are mentioned. The description notes the optional `page` parameter and default overview, but this is parameter behavior rather than guidance about choosing this tool versus the many sibling get_* and list_* 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?

Without annotations, the description carries the burden of disclosing behavior. It mentions error conditions ('Errors when the host has no values.json yet') and describes the output structure (every value is {value, type} with specific type options). It does not mention side effects, permissions, or rate limits, but for a read-only get operation, the provided transparency is adequate.

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 main action ('Get the platform facts') and then provides valuable details about the return type, categories, and error behavior. It is somewhat lengthy but not overly redundant; every sentence adds useful information. Structure is logical and clear.

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 must fully explain the return value. It does so thoroughly: lists the categories (versions, counts, dates), the type format, the inclusion of mcp_tools, and the error condition. Nothing essential is missing for an agent to use the tool correctly.

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 zero parameters, and the schema fully covers this (100% coverage). According to the rubric, 0 params results in a baseline score of 4. The description adds no parameter explanations, but none are needed.

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 retrieves platform facts (versions, counts, dates) as typed values, and explicitly distinguishes it from other tools by mentioning it returns the same data as /website/values.json plus mcp_tools. The core action and resource are 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?

The description explains what the tool returns but does not explicitly state when to use this tool over siblings. It implies it is for platform facts, but lacks direct comparison or conditions such as 'use when you need the full platform data instead of individual get_* tools.' No explicit usage guidance is provided.

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 explains the output structure (plain-text intro, images with full-size and thumb URLs) and the key semantic of imageMode (tiles purposefully repeat the same full-size URL). This adds meaningful beyond-schema context, though it doesn't mention permissions or potential errors.

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 focused sentences that front-load the main purpose, then add necessary behavioral details. No word is wasted; the imageMode explanation earns its place by disclosing a non-obvious behavior.

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, the description covers the essential input (project id), output (intro and image structure), and the special case (tile mode). It lacks a mention of language behavior or error handling, but those are minor gaps; the overall description is complete enough for correct selection and invocation.

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?

Input schema covers 100% of parameters (id and lang) with descriptions and examples. The description reinforces the role of id but adds no extra parameter-level information; lang is not mentioned at all. With high schema coverage, baseline 3 is appropriate.

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 a specific action ('Get') and a precise resource ('project intro plus its images') keyed by project id, clearly distinguishing it from sibling tools like get_docs or get_epos. It also adds unique return-value characteristics (image URLs, thumbnails, imageMode) that make the tool's purpose unmistakable.

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 when you have a project id and need intro/images, but it does not explicitly reference alternatives such as list_projects for discovering ids, nor does it state use cases to avoid. The guidance is clear but implicit rather than explicit.

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, but it only mentions the return format without disclosing behavioral traits like authentication needs, rate limits, or side effects. 'Get' implies read-only, but this is not explicit.

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, concise sentence that front-loads the verb and resource, with no unnecessary words. Every part 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?

The description specifies the return fields but lacks broader context such as when references are used in the workflow, how they relate to other tools, or whether any prerequisites exist. Adequate for a simple tool but not thorough.

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?

There are no parameters, so schema coverage is 100%. Baseline is 4 per rubric; no additional explanation needed 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 it 'gets external design references (Behance projects)' and specifies the output fields, making the purpose unambiguous and distinct from sibling tools which target different resources.

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 on when to use this tool versus alternatives; no context about prerequisites or typical use cases is provided.

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 present, the description carries the full burden and provides rich behavioral context: it explains that the tool returns partial data (timeline intro as plain text), the structure of each station (years as written text and numbers, null `to` indicates current), and highlights the oldest station's content. It gives a sense of data shape and edge cases (null for 'still there') that go beyond a simple getter. It could mention rate limits or data freshness, but for a resource fetch tool, this is quite thorough.

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 packs an enormous amount of useful information into three sentences. It's front-loaded with the core purpose, then details the exact structure of the return value, and ends with a routing hint to a sibling tool. Each sentence provides unique value with no fluff. It's slightly long, but every part informs the caller about what to expect.

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 no output schema and no annotations, this description is remarkably complete. It explains the return structure, data types, edge cases, and even gives a historical note about the content ('the oldest, `history`, holds the first jobs'). An agent has everything it needs to understand the return value and call the tool correctly for this simple resource fetch.

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 covers 100% of the parameters, so the baseline is a 3. The description adds a small amount of nuance by mentioning the default language ('Language (default en)'), which the schema also indicates. The description doesn't need to add much since the schema is complete for the single, optional `lang` parameter.

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 explicitly states what the tool returns: the professional career timeline/CV of Markus Lungwitz, including its structure (timeline intro, shelf, full stations). It also explicitly differentiates itself from the sibling `get_timeline_station` by naming it as the tool for a single station. This provides maximum clarity for an agent.

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 guidance on when to use this tool versus the named sibling, `get_timeline_station` ('For one station alone use get_timeline_station'). It effectively communicates the scope, showing it fetches all eight stations at once. However, it does not discuss scenarios like pagination or caching since there is none, which is fine. The guidance is strong enough for an agent to route correctly.

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 behavioral burden. It discloses the key behavior: the tool returns years, description, keywords, and all texts, and unknown ids return the list of stations instead of an error. This is meaningful behavioral information beyond 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 dense sentence front-loads the action and resource, gives concrete examples, lists the returned content, and states the unknown-id fallback. Every clause contributes value with no filler.

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-parameter read tool with no output schema or annotations, the description is close to complete: it states what is returned, the accepted identifier forms, and the behavior for unknown ids. Minor ambiguity remains in 'all texts' and the exact shape of the fallback list, but these do not prevent correct invocation.

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. The description adds examples and the folder-name interpretation ('history (the first jobs 2004–2006)') but the schema already enumerates the accepted values and lang is documented with an enum. No significant semantic gap remains.

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 a specific verb and resource: 'Get one station of the career timeline by id or folder name.' It distinguishes this from the sibling get_timeline by explicitly saying 'one station' and lists concrete examples. The purpose is unmistakable.

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 clarifies selection by id or folder name and describes the fallback for unknown ids. It does not explicitly name get_timeline as the alternative for retrieving the full timeline, but the singular scope implies that distinction clearly.

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 provided, so description carries full burden. Describes returned data structure but lacks details on permissions, error conditions, or other behavioral traits.

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 sentence, front-loaded with verb and resource, no wasted words.

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?

Adequately covers the tool's simple functionality and output structure, though could mention limits or pagination.

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 covers the single parameter fully (id, starts with PL). Description adds minimal extra meaning 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?

Description clearly states it gets a single YouTube playlist by ID, including its videos with specific fields. Distinguishes from sibling list_youtube_playlists.

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?

Implies usage when retrieving a specific playlist by ID, but no explicit guidance on when not to use or alternative tools like list_youtube_playlists.

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 provided, so description carries full burden. It discloses output fields but does not mention rate limits, authentication, pagination, or ordering behavior.

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 sentences, action verb first, no filler. Every sentence adds value.

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 list tool with one optional parameter, the description is mostly complete. It states purpose, filter, and output fields. No output schema exists, but description compensates by listing fields.

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 description for category. The description adds value by providing example categories (framework, language, tooling, design, os) beyond the schema's minimal description.

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 clearly states 'List all tech/tool buzzwords' and specifies output format as {id, label, category}. This distinguishes it from sibling tools like get_buzzword (single item) and search_buzzwords (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?

Description implies usage via an optional category filter with examples. However, it does not explicitly state when to use this tool versus alternatives (e.g., get_buzzword for a single buzzword, search_buzzwords for full-text search).

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 burden. It describes the action as listing (read-only) but does not explicitly state safety, permissions, or side effects. The behavior is implied but not fully disclosed.

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?

Single sentence, front-loaded with verb and resource, no wasted words. Every part contributes meaning.

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 parameters and no output schema, the description covers the key purpose and resource. Missing details like output format or pagination, but acceptable for a simple list 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?

No parameters exist, so schema coverage is 100%. Baseline for zero parameters is 4; the description adds no further parameter info, which is acceptable.

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 it lists auto-generated code documentation sets (Compodoc) for the specific moja-work monorepo, including URLs. This distinguishes it from sibling tools like get_docs (which retrieves a single doc) and list_buzzwords.

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 for listing all documentation sets but does not explicitly state when to use it versus alternatives like get_docs for specific docs. No when-not or alternative names provided.

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 provided, so description carries the burden. It discloses sorting behavior (newest first by update date or release date), the fields (release/update as written, date as ISO, description, link, url), and that dates are as written. It doesn't mention rate limits or error cases, but for a list tool that's mostly sufficient. It does go beyond what schema shows.

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?

Single sentence with dense info: purpose, content, sorting, and field details. A bit long but each clause adds value. Front-loaded the main action. Could be split into two sentences for readability, but no 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 simple list tool with one optional lang param and no output schema, the description covers the what, content, sorting, and field structure. It doesn't specify pagination or limits, but not necessarily needed. It's fairly 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 covers 100%: lang enum with description 'Language (default en)'. Description doesn't add any parameter-specific detail beyond the schema, but the schema fully defines it. Baseline 3 for high coverage is appropriate.

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?

Clear verb (List) + resource (news of moja.work start page). Specifics: dated release notes, one per application/milestone. Distinguishes from siblings (all start with get_/list_, but none list news).

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 alternative is named, but the context is clear: it lists news for the start page, and siblings are all get/list for other resources. The description implies when to use (when you need news entries) and doesn't need exclusions because the tool is unique among siblings. Not explicit enough for 5, but clear.

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 provided. The description indicates a read operation, but does not explicitly state side effects, authorization needs, or destructive behavior. It 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?

Single sentence front-loads the core purpose and adds a value proposition. No wasted words; highly efficient.

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 list tool with one optional parameter and no output schema, the description is complete: it specifies returned fields and eliminates follow-up calls. Lacks pagination/ordering details, but those are not critical.

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% and the description adds no additional meaning to the lang parameter beyond the schema's enum and description. Baseline score is appropriate.

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 DIY/design projects, specifies returned fields (id, headline, intro), and highlights that the intro eliminates follow-up calls. It distinguishes from sibling tools like get_project.

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 for listing all projects with a benefit over get_project, but lacks explicit when-to-use or when-not-to-use guidance. No alternatives are named, though siblings are available.

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, but description indicates it is a read operation (listing public playlists). However, it does not disclose any behavioral traits beyond that (e.g., rate limits, auth requirements, or empty list behavior).

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?

Single sentence, perfectly concise and front-loaded with the action and resource.

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 parameters and no output schema, the description fully covers what the tool does and what it returns. The output fields are explicitly listed.

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?

No parameters, so baseline of 4. Schema coverage is 100% (empty schema fully described). Description adds no parameter info, but none needed.

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?

Clearly states it lists the public YouTube playlists of the moja.work channel and specifies the exact fields returned. Distinguishes from sibling 'get_youtube_playlist' by using 'list'.

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 on when to use this tool versus alternatives like 'get_youtube_playlist'. Implies listing all playlists but does not explicitly recommend it.

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 provided, so description bears full burden. Mentions 'returns matching entries with a snippet', but lacks details on case sensitivity, fuzzy search, pagination, or read-only behavior.

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?

Single sentence efficiently conveys purpose and output. Front-loaded with key info; no wasted words.

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, so description should specify return structure more precisely. Vague on result details (e.g., pagination, max results, ordering). Incomplete for a search 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% with clear descriptions for both parameters. Description adds context about full-text search and snippet but does not enhance parameter meaning 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?

Clearly states verb 'Full-text search', resource 'buzzword glossary', and output 'returns matching entries with a snippet'. Distinguishes from siblings like list_buzzwords and get_buzzword.

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?

Implies usage for searching glossary, but no explicit when-not-to-use or alternative tools mentioned. Sibling tools like list_buzzwords could be alternatives for browsing.

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