Niels Langereis

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

Annotations already mark it read-only, idempotent, non-destructive, and closed-world. The description adds important behavioral context: contact is via email or site form and this server does not send messages, which prevents an agent from expecting a messaging action.

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

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

Three sentences, front-loaded with purpose and usage, then a contact constraint. Minor repetition of 'background' but generally 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?

Given a simple read-only info tool with one optional enum parameter and no output schema, the description covers what it returns, when to use it, and an important contact limitation. Nothing critical is missing for an agent to invoke it 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?

Schema coverage is 100% and the single optional topic enum is fully documented with a default. The description's list of content areas (services, background, speaking, contact) loosely maps to the enum values but does not add parameter-specific syntax or selection guidance 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 states the tool returns information about Niels Langereis: who he is, how to work with him, his background, talks, and contact. It is specific and the resource is clear, though it does not explicitly differentiate from siblings like get_essay or search_essays.

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 gives explicit use cases: when someone asks whether he could help, wants to hire/book him, or wants his background. No alternatives or when-not conditions are named, but the context is 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?

Annotations already cover the safety profile (readOnly, idempotent, closed-world, non-destructive), so the bar is lower. The description still adds real context: the two-tier detail output, the optional filters, and notably that rendering depends on client capability ('Shows an interactive map where the client supports it'), 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?

Purpose is front-loaded in the first clause and the detail-level guidance comes before the filter note. The middle run-on describing 'the coordination layer, the bench and the external renderers that decide whether faster work becomes a better organisation' is padded and slightly promotional, keeping this out of the top band.

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, the description usefully explains what each detail mode returns (skeleton vs full prose), and all three optional parameters are accounted for. Nothing an agent needs in order to invoke it correctly is missing; only return-shape specifics like size or pagination are unaddressed.

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%, with both enums (phase, detail) already explained in-schema, so the baseline of 3 applies. The description's 'Optionally filter by function or phase' largely restates the schema rather than adding new syntax or semantics.

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 exactly what the resource is (24 illustrative AI agents across ten named business functions, each with rollout phase, optimisation target and cross-functional trade-off) and clearly separates this artifact from siblings like get_essay, search_essays or run_skill_matrix. An agent can tell what it will get without opening the schema.

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 gives a concrete use case ('Use it to reason about someone's own AI rollout') and tells the agent which detail level to pick by default ('summary... is enough for most reasoning'). It stops short of naming an alternative tool or a when-not-to-use condition.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds useful context beyond that: the response is Markdown and includes the date plus both the site and original LinkedIn links, which tells the agent what it will actually get back.

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 compact sentences with no filler; the core action and its outputs are front-loaded before the argument-sourcing hint. Every clause carries information the agent needs.

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, and the description compensates by enumerating the returned fields (full Markdown text, date, site link, LinkedIn link). Combined with the id/title sourcing note and rich annotations, nothing needed to call this one-parameter read tool 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 parameter is fully documented as 'Essay id (from search_essays) or its title'. The description restates the same dual-acceptance rule (id or title) without adding syntax, format, or fallback behavior, 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 a specific verb and resource ('Get the full text of one essay by Niels Langereis') and even enumerates the returned components (Markdown text, date, site link, LinkedIn link). It is clearly distinguishable from the sibling search_essays, which handles discovery rather than 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?

It tells the agent exactly where the argument comes from ('Use the id from search_essays, or a title'), which is genuine routing guidance toward the sibling tool. It does not state any when-not-to-use condition, but for a simple single-record fetch there is little alternative to exclude.

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), so the description's job is to add content-level expectations. It does so by listing the included sections (status rule, how to read it, worked example, credits), which tells the agent what it gets back in the absence of an output 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?

Two sentences, no filler. The core purpose is stated first and the usage hint is placed last, so the agent gets the what and the when in a minimal, well-ordered package.

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 parameters, no output schema, and annotations already declaring the read-only profile, the description supplies exactly the missing piece: a preview of the document's contents and the point at which to fetch it relative to run_skill_matrix.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter discussion is needed or missing.

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 ('Explains') and a specific resource (Langereis's skill-matrix gap analysis), and enumerates what the explainer contains (status rule, reading instructions, worked example, credits). It names run_skill_matrix as the sibling it complements, though it doesn't distinguish itself from get_essay or about_niels.

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?

Gives an explicit trigger condition: 'Use before run_skill_matrix if the user wants to understand the method first.' That routes the agent cleanly in that scenario, but offers no guidance for other cases (e.g., when to read the method vs. just run the matrix outright).

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?

The annotations only cover safety (readOnly, idempotent, non-destructive). The description goes well beyond that: it discloses the interactive edit loop, that the user-edited matrix returns to context, what the result flags mean ('At risk', 'Thin', 'Reps gone'), and the fallback bench behavior. No assertion conflicts with the read-only 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?

Purpose and output are front-loaded, and every sentence carries actionable instruction. The middle paragraph is dense with parenthetical asides, which slightly hurts scannability, but there is little redundancy.

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, the description carries return-value explanation and does so: it names the matrix, the three risk flags, and the post-edit context flow. Combined with the parametrization guidance, an agent has everything needed to call it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: how many competencies to author (6-10), the bench default of 1 with the 'estimate they should correct' caveat, and the omit-to-use-example behavior. It does not, however, explain the who/category/tactical/execution fields 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?

States a specific verb and resource ('Runs ... skill-matrix gap analysis for one role') and says exactly what it produces ('interactive matrix the user can edit'). This is clearly distinguishable from siblings like get_skill_matrix_method (the method) and get_enterprise_ai_map (the phase map).

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?

Gives explicit operational conditions: draft 6-10 competencies yourself, use bench=1 with an 'estimate' caveat when unknown, and omit competencies to show the generic analyst example. It never names a sibling as an alternative or states exclusions, so it falls short of a full 5.

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

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

With readOnly/openWorld/idempotent/destructive annotations already covering the safety profile, the description still adds real substance: what a result contains (titles, dates, summaries, a matching snippet, links) and the default ordering when the query is empty. It stops short of describing ranking behaviour or the practical result limit, which is a minor 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?

Three dense sentences: scope first, output shape second, the empty-query behaviour and the follow-up routing last. No filler, and the routing instruction is front-loaded enough to be acted on.

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 carries the burden of describing the return payload, and it does so (titles, dates, summaries, snippet, links). Combined with the empty-query semantics and the hand-off to get_essay, an agent has everything needed to call this 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?

Schema coverage is 100% and the parameter's own description already states both the topic-question form and that an empty value lists everything, so the description's 'Leave query empty to list all essays' largely restates the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (search) and resource (Niels Langereis's essays) and enumerates the topical scope, so an agent knows exactly what corpus this covers. It also distinguishes itself from the sibling get_essay by naming it as the follow-up for full text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit operating conditions: empty query lists everything newest-first, and 'Follow up with get_essay for the full text before quoting him' names the alternative tool and the condition that selects it. Nothing is left to inference.

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