Pieter-Jan Scheir

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the returned field inventory, which is useful, but says nothing about localization behavior despite the locale parameter, and there is no output schema to compensate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that enumerates the resource contents with zero filler. Nothing wasteful, nothing deferred.

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 read-only, zero-required-parameter tool the description is nearly sufficient, and annotations cover safety. The notable gap is the multilingual intent of the tool: 35 supported locales exist but the description never hints that the profile can be returned in a chosen language.

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 sole locale parameter is fully documented with 35 enum values and a default, so the schema carries this dimension. The description adds no additional meaning about localization or how locale affects the answer.

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 the specific resource (Pieter-Jan Scheir's profile) and enumerates its contents — positioning, about text, roles, links, email — which lets an agent separate it from siblings like get_skills or list_experience. The retrieval verb is only implicit, but the resource is 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?

There is no statement of when to call this instead of get_skills, list_experience, or how_to_contact, nor any prerequisites or exclusions. Usage must be inferred entirely from the content list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only that the response covers 'everything' about the project, which hints at a comprehensive payload versus the list variant, but discloses no auth, rate-limit, or missing-project 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?

A single ten-word sentence that is front-loaded with the resource and scope. Nothing is padded or redundant.

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?

With no output schema and no return-value description, the agent knows neither the shape nor the fields of the 'everything' payload. For a detail-fetch tool this is an acceptable but noticeable gap, partially offset by 100% schema coverage on inputs.

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%: the id parameter is documented as coming from list_projects and the locale parameter's meaning and default are in the schema. The description mentions only the id, adding nothing about locale, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (get) and resource (one project), and the 'by its id' phrasing makes the single-item scope clear, which implicitly contrasts with the sibling list_projects. It never names the sibling explicitly, so sibling differentiation must be inferred.

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?

There is no when-to-use guidance, no statement of prerequisites, and no mention of alternatives such as list_projects for browsing. The agent must infer from the name alone that this is for fetching one known project.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety behaviour is covered. The description adds only that the response contains certifications, languages and tools — useful but minimal, with no note on scope (whose skills) or result size. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with the resource front-loaded — no filler. It is under-specified rather than verbose, which is a completeness problem, not a conciseness one.

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, annotation-covered read tool with one optional param, the description is adequate but thin: it does not identify whose skills are returned, whether the result is a full inventory, or how it relates to the sibling listing tools. With no output schema, the brief content summary carries the return-value load.

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?

Only one optional parameter (locale) and it is fully documented in the schema with a default and an enum list, so schema coverage is 100%. The description adds nothing about locale or localized output, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource (skill areas, certifications, languages and tools) so an agent can infer retrieval, but it is written as a noun phrase with no explicit verb and uses an ambiguous 'His' with no stated subject. It is distinguishable from siblings like list_experience or get_profile only by inference, not by anything the text says.

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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to or away from alternatives such as list_experience or get_profile. The agent must guess whether this returns a full skills inventory or a summary.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety and side-effect profile is fully covered elsewhere. The description adds the payload content (email, calendar link, contact page), which is useful, but contributes nothing about freshness, rate limits, or auth.

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 short sentence with the resource front-loaded and the returned channels enumerated after the colon. No filler, though the phrasing 'How to reach him' is informal and could be tightened into an explicit verb-resource statement.

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 zero-required-parameter, read-only lookup with annotations covering the safety profile and no output schema, the description tells the agent what it does and what it returns. Nothing essential to invoking it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'locale' parameter is fully documented in the schema with its enum and default. The description mentions no parameters, so it adds nothing beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (contact channels: email, calendar link, contact page) and a scope ('for development work'), so an agent knows this returns ways to reach the person. It is clearly distinct in intent from get_profile, get_skills, or list_experience, though it never explicitly contrasts itself with them.

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?

There is no statement of when to use this tool versus alternatives, nor any prerequisite or exclusion. 'For development work' hints at a context but is not an actionable usage rule, leaving the agent to infer when contact info is the right call over get_profile.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and non-open-world behavior, so the safety profile is covered. The description adds meaningful behavioral context by specifying the output order ('newest first') and the fields returned (company, period, description, stack, page), which is more than the annotations provide, though it stops short of explaining pagination or what 'page' actually represents.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient fragment with no wasted words and the most important information (roles, newest-first ordering, returned fields) front-loaded. It is arguably too terse and cryptic in places, which keeps it from a 5.

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 read-only list tool with one fully documented optional parameter, no output schema, and annotations covering safety, the description is adequate but leaves clear gaps: it does not clarify what 'page' means, offers no usage guidance versus siblings like get_profile, and relies on external context for 'His'. It is minimally viable rather than 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 coverage is 100%: the single optional locale parameter is fully described in the schema as 'Language of the answer (default en)' with an enum and default. The description does not add any parameter details beyond that, so the baseline of 3 is appropriate when the schema already does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource ('His roles') and ordering ('newest first'), then enumerates the returned fields (company, period, description, stack, page). This distinguishes it from siblings like list_projects and get_skills, though it lacks an explicit verb such as 'list' and the possessive 'His' relies on external context to identify the subject.

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 offers no when-to-use guidance, no prerequisites, and no comparison to alternatives such as get_profile or list_projects. An agent must infer that this tool is for retrieving work experience rather than related sibling resources.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful ordering semantics — projects with a year newest first, then alphabetical — which the annotations do not convey.

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 the resource and ordering, then the filters. No filler; only the slightly informal 'His projects' opening costs a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries the return-value burden and does so by listing stack/status/link and the ordering. Locale-based answer language is documented in the schema. Nothing essential is missing for a read-only listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%: locale and technology carry their own descriptions, while category and featured are bare enums/booleans. The description compensates by naming the three filter dimensions (technology, category, featured), so an agent understands what each selector does despite the thin schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (list) and resource (projects) plus what each entry contains (stack, status, project link) and the sort order. It is clearly distinguishable from the singular get_project sibling, though it never names that sibling explicitly.

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?

Filtering options (technology, category, featured) imply when to use this list versus the single-project tool, but there is no explicit when-to-use/when-not statement or reference to an alternative tool.

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