Claspine

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description usefully adds what is returned per mode, including that schemas are resolved, which is behavior the agent cannot infer from 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?

Two dense sentences with the scoping modes front-loaded and no filler. The telegraphic 'Without path: / With path:' style is efficient, though slightly terse for a reader unfamiliar with the 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?

With no output schema, the description carries the return-value burden and does so for both modes (operation list vs parameters/body/responses with resolved schemas). Few remaining unknowns for a two-optional-parameter read 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%, so path and method are already documented in the schema, including the example path and the method default. The description restates the path/method effect but adds only the 'all operations vs one operation' framing, which fits the baseline 3.

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 precisely what the resource is: the published HTTP contract under /api/v1 shared by Atlas and the self-hosted engine. The 'HTTP' framing implicitly separates it from the java_api sibling, though no sibling is named 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?

Explains the two operating modes clearly: no path returns every operation, path (plus method) returns that operation's parameters, body and responses. It stops short of saying when to prefer this over search_docs, get_guide or java_api, so there are no explicit 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description correctly spends its words elsewhere: it discloses data handling ('analysed in memory and not stored') and, importantly, sets an expectation ceiling ('A clean result is not proof of safety'). It also names the shape of the result (file, line, rule, fix) with no output schema to lean on.

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

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

Four short sentences, capability first, then return shape, then privacy, then the accuracy caveat. The rule enumeration is long but each item is decision-relevant for judging whether this tool covers a given concern; nothing is padding.

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 supplies the return fields, the data-retention behavior, the diff-scoping semantics, and an explicit false-negative warning. For a read-only analysis tool with two optional parameters, an agent has everything needed to call it and interpret the answer.

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 already explains both modes, including that only added lines in a diff are checked and that path determines browser vs server classification. The description restates the two input modes but adds no syntax, size limits, or precedence rule when both are supplied, 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?

Opens with a specific verb+resource ('Runs Claspine's Agent Shield rules on files or a unified diff') and then enumerates the concrete rule classes it detects (secrets, string-built SQL, unscoped tenant queries, log leaks, buffered uploads, platform-internal imports). Unmistakable against the doc-lookup siblings like api_reference, get_guide or search_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?

The two accepted input modes (files vs unified diff) make the intended call context clear, and the closing line routes the agent to a complementary check ('Spring Boot builds also run ProductBoundaryTest'). It stops short of an explicit use-this-when / not-this-when statement, so it is clear context rather than full routing.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds meaningful context beyond that by stating "Content is not stored" and enumerating the specific validation categories, though it does not describe return shape or severity levels.

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 dense and front-loaded: it first states what is checked, then lists the risk categories, then closes with the privacy note. Every clause contributes, though the long inline list is slightly less scannable than a structured breakdown.

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 tool is a read-only checker with no output schema and two parameters. The description explains what it checks but not what the caller receives—such as whether it returns violations with line numbers, severities, or a pass/fail summary—which is a notable gap for a diagnostic 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 fully documents both parameters. The description reinforces the source types (YAML/properties/env) that map to the format enum but adds no additional format syntax or defaulting details 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 a specific verb ("Checks") and resource scope (application.yml, application.properties, or environment variables), and it names concrete issue categories. It is clearly about configuration validation rather than code or documentation, but it does not explicitly contrast itself with the sibling check_code tool.

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 usage is implied by the resource types and the listed checks, but there is no explicit guidance on when to choose this tool over check_code or other siblings. No exclusions or prerequisites are stated.

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, so the safety profile is covered. The description adds real behavioral content the annotations do not: it parses specific file types and returns the checklist items of all upgrade notes up to the target, and the schema notes target defaults to the latest release.

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 with the primary action front-loaded and no filler. It is slightly packed — the file list and the return content are compressed into one clause — but nothing is wasted.

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, and the description does state the shape of the return (checklist items from every upgrade note up to the target), which covers the main gap. Defaults and per-parameter meaning are handled by the schema, so an agent has enough to call it.

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 all three parameters are already documented in structured form. The description only lightly reinforces the files-vs-current duality ("or takes it as given") without adding syntax or precedence rules 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?

Uses specific verbs (finds, lists) on a concrete resource (Claspine version in named project files / upgrade-note checklist items). That is clearly distinct from upgrade_notes and check_config in substance, but the description never names a sibling to make the distinction explicit.

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?

"or takes it as given" implies two input modes (files vs. current), which is useful context. However, there is no statement of when to call this rather than upgrade_notes or get_guide, and no 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?

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the description is free to spend its words on content — and it does, listing the returned fields and noting it covers fixes for 'common ones,' which sets expectation that some codes may lack a fix. With no output schema, that enumeration is genuinely useful disclosure. It doesn't say what happens on an unknown/malformed code, which keeps it off a 5.

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, zero filler, with the payload contents front-loaded ahead of the sourcing note. Efficient and easy to scan.

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 one-parameter read-only lookup with no output schema, the description supplies the return shape and honestly scopes fix coverage to 'common ones.' Missing only edge behavior — unknown code, case sensitivity — which is a minor gap given how simple the tool is.

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 is a single parameter and schema description coverage is 100%, including the HOST_NOT_AVAILABLE example, so the schema does the heavy lifting and baseline 3 applies. The description adds only the marginal hint that codes come from error responses, no format or casing 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 names a specific resource (a Claspine error code) and enumerates exactly what the answer contains: HTTP status, the messages it is raised with, where it is raised, and the fix. That is far more than a restatement of the title. It stops short of a 5 because it never distinguishes itself from the sibling check_code, which an agent could plausibly confuse with this lookup.

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?

Usage is only implied: 'Every Claspine error response carries its code' tells the agent where the input comes from, which indirectly signals 'use this when you have an error code.' There is no explicit when-not, no prerequisite, and no mention of when to prefer api_reference or search_docs instead.

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 safety needs no restating. The description's added value is disclosing the return payload's composition, which matters because there is no output schema. It omits edge behavior such as invalid-slug handling or document size, keeping it below a 5.

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 zero waste, and the payload contents are front-loaded so an agent can decide quickly whether this is the right 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?

With no output schema, the description usefully enumerates what the response contains, and the one required parameter is fully documented in the schema. Missing only minor operational details (failure modes on unknown slugs, output length) 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?

There is a single parameter with 100% schema description coverage, including a concrete example ('sign-in-engine') and a pointer to search_docs, so the baseline is 3. The description contributes no additional slug semantics such as case sensitivity or format rules.

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 precisely enumerates what is returned — steps, code, settings, safety notes, troubleshooting — so an agent knows this is a full-content retrieval tool, not a search. The title supplies the verb ('Read'). It stops short of differentiating itself from the sibling get_recipe, which likely returns similarly structured recipe content, so the agent must infer the guide/recipe distinction.

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?

Usage is only implied: 'one Claspine guide' signals that a specific guide must already be identified, so discovery should precede this call. The schema's slug description points to search_docs, but that routing cue lives in the schema, not the description, and no when-not-to-use case (e.g. versus get_recipe or api_reference) is stated.

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 read-only, idempotent, non-destructive and closed-world, so the bar is lower. The description adds real value beyond them: recipes are validated against the live API on every build (a freshness guarantee), reads are non-mutating and safe to repeat, and the return shape flips between a single recipe and a list depending on whether task is supplied -- important given there is no 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 tight sentences with the core capability front-loaded and the no-task fallback appended where it belongs. The language list partially duplicates the schema enum, but it reads naturally and costs little.

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?

All three parameters are optional and fully documented, there is no output schema, and the description covers both possible return shapes plus a freshness guarantee. What is thin is the routing story against ten sibling tools, which the description does not address at all.

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 per-parameter descriptions and enums for form and language, so the schema carries the semantics. The description echoes the supported languages and both deployment forms but adds no syntax or format detail beyond that, and does not clarify the 'all' language option.

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?

Specific verb+resource: it returns copy-ready HTTP call recipes for a named task, in a chosen language and form. It is clearly distinct in kind from siblings like search_docs or explain_error, but it never names an alternative or states the boundary against api_reference or get_guide, so the agent must infer which of the reference-ish tools to pick.

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?

"Without task: the list" implies a browse mode versus a lookup mode, which is genuine usage guidance, but no when-to-use or when-not-to-use condition against siblings is given. Nothing tells the agent whether api_reference or get_guide is preferred for API surface questions.

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 state readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds that the data comes from the current platform build and that no arguments returns capabilities, but it does not describe return format or limits.

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 short and front-loads the core resource being returned. The final fragment about no arguments is slightly abrupt but still useful and not wasteful.

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 read-only lookup tool with two optional parameters and no output schema, the description identifies the kind of content returned but does not explain the result shape or how type/capability results differ. It is adequate but leaves some ambiguity about the returned artifact.

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 both optional parameters have examples in the schema. The description only adds that omitting arguments returns capabilities, which is useful but does not significantly expand 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 specifies the resource clearly: public Java types from a capability's api package and the foundation, including methods and record fields from the current platform build. It does not differentiate this from the sibling api_reference tool, so it falls short of a 5.

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 says what happens without arguments, but it does not explain when to use this tool versus alternatives such as api_reference, search_docs, or get_guide. It provides only implied usage 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?

Beyond the annotations (readOnlyHint: true), the description adds valuable behavioral context by explaining that it returns 'the best matches first' and accepts 'a plain question or keywords'.

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 definition is highly concise and front-loaded. Every phrase contributes directly to the agent's selection process, with no superfluous language.

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 complexity (a search/lookup tool) and the presence of sibling tools (get_guide, get_recipe), the description provides all necessary context for the agent to use it effectively and know when to hand off the conversation.

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?

Since the schema coverage is 100%, the description does not need to clarify parameter details; it correctly provides context on the required input type ('plain question or keywords') which complements 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 resource it searches (guides, recipes, capability table, error fixes) and the action (Search), distinguishing it from sibling tools like get_guide.

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 provides explicit workflow guidance: the results are the best matches with links, and the user should subsequently use get_guide or get_recipe based on the results.

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 this a safe, idempotent read. The description adds ordering ('oldest first') and the shape of the content returned, which are useful behavioral details beyond the annotations. Minor gaps remain around whether the range is inclusive and how results are bounded.

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, and the ordering/content summary is front-loaded ahead of the actionable instruction. Every sentence 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?

With no output schema, the description usefully explains what the notes contain and their order. It is nearly complete for a simple two-parameter read tool, lacking only clarification of range inclusivity and any result limits.

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 both parameters are already documented, including the default for 'to'. The description's 'after one version up to another' hints at range semantics but is ambiguous about whether 'from' is exclusive, adding little over 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 resource (Claspine upgrade notes) and scope (between two versions), with content described (changes, checklist, pre-deploy steps). It clearly separates itself from docs-oriented siblings like api_reference or get_guide, though it does not explicitly name a sibling tool.

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?

'Read them all before changing the Claspine version' gives a clear trigger for use. It doesn't mention alternatives (e.g., check_upgrade) or when not to use it, so it falls short of the explicit routing a 5 requires.

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 closed-world, so safety is covered. The description adds real value by warning that capabilities differ between deployments and citing a concrete gap, but it does not say what the response looks like (matrix? list?) or how gaps are represented, so transparency is good but not rich.

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 scope statement comes first and the decision-relevant caveat second, so an agent gets the gist immediately.

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 lookup with no output schema, the description conveys what the result means (which capabilities exist on which deployment) and why it matters before integration planning. It stops short of describing result shape or how to interpret partial matches, which is a minor gap.

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 optional 'capability' parameter is documented in the schema with an example ("sign-in", "payments"). The description adds no filtering syntax or semantics beyond that, so the schema carries the burden and 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 states a specific resource and scope: a capability-availability matrix across Claspine Atlas, self-hosted engine, and self-hosted Spring Boot. The verb is implicit ("which capabilities exist"), but the resource and comparison axis are precise enough that an agent can distinguish it from sibling doc-lookup tools like search_docs or api_reference.

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 an explicit usage rule: "Check this before planning any Claspine integration," which tells the agent when to reach for it. It also supplies a concrete divergence example (Atlas lacks sign-in, permissions, push) that motivates the call, though it does not name a specific alternative tool to use for other cases.

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