Ptally

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

The annotations already establish that this is a read-only, idempotent, closed-world operation. Beyond that, the description adds useful workflow sequencing and content scope, but it does not clarify response format, documentation size, or whether the material is version-specific.

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 front-loads the operation and the critical BEFORE workflow instruction, then presents a compact topic map. The final sentence is dense, but every clause helps the agent choose a topic and there is 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 one-parameter read with a fully documented enum, the description supplies the workflow prerequisite, topic contents, and recommended entry point needed for correct invocation. The lack of an output schema or explicit response format is a minor gap that does not materially impede selection or parameterization.

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?

Although schema coverage is 100%, the description substantially expands both enum meanings: "rules" includes expression syntax, quality gates, and debugging, while "readme" covers step types, query language, input/output blocks, and examples. The "start here" guidance also communicates intended parameter selection rather than merely restating allowed values.

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?

"Fetch Ptally documentation by topic" gives a specific verb and resource, and the detailed topic map clarifies the documentation's scope. It does not explicitly distinguish this tool from siblings such as get_schema or get_starter, so selection against those alternatives still requires some inference.

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 workflow trigger—call before building or editing a config—and recommends starting with the "rules" topic. The topic explanations also provide practical selection guidance between a rules-oriented briefing and the full engine reference.

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, and openWorldHint=false, so the safety profile is covered. The description adds behavior those annotations do not capture: it performs a real probe by counting rows in the projects and quotes tables and reports latency and an error shape, which tells the agent the call touches a live store and can fail in a way worth retrying.

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 purpose and then documents the exact fields returned, so the agent knows what to expect. Both sentences are dense with useful detail, and although the second is long, nothing in it 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?

There is no output schema, so the description must carry the full burden of documenting the return value, and it does: it names every field and both success and failure shapes for `store`. For a zero-parameter read-only diagnostic tool, nothing needed to call it or interpret it 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?

The tool takes no parameters, and the schema is empty, so there is nothing for the description to explain. The baseline of 4 applies because no parameter semantics 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 states a specific verb and resource: a "diagnostic snapshot of the deployed MCP server plus a live probe of its store". That clearly separates it from the data-reading siblings such as get_project, get_schema, and run_quote, since this tool reports server and store status rather than domain content.

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 never says when to call this tool or that other tools exist for other needs; usage can be inferred only from the words "diagnostic" and "health check" in the title. A single clause such as "use this to verify connectivity and data availability before other calls" would make the guidance 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?

Far beyond the readOnly/idempotent annotations, the description discloses version fallback resolution (live, then any non-archived status), that a foreign version_reference is a tool error, the 100-row clipping threshold, which collections become patchable versus download-amend-upload only, and that the returned model is a reading summary and not a file. These are exactly the operational traits an agent needs to avoid misuse.

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 core action and the version rule are front-loaded, and every later sentence carries load because there is no output schema to defer to. The enumerated return-field list and the dense parenthetical describing __context keys make it heavy to parse, but nothing is truly 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, the description fully carries the return contract: field names, the meaning of latest_draft, the clipping/patchable distinction, and what content is returned verbatim for building input payloads. For a read tool feeding run_quote and patch_version, nothing an agent needs in order to call it and interpret the result 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 coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: the cross-project constraint on version_reference (a tool error), the ordered fallback chain when it is omitted, and the fact that patches land on latest_draft. The only shortfall is that project_reference itself gets no added semantics beyond the schema's UUID note.

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 first clause gives a specific verb and resource ('Fetch a project by `project_reference` from the self-host store') and immediately scopes it against the plural sibling by explaining the version-resolution behavior. An agent can tell this apart from get_projects, run_quote, and patch_version without opening any 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 explicitly positions the tool as a 'precursor to run_quote and patch_version' and gives a concrete follow-up loop ('call get_project again with its version_reference before patching'). It also instructs the agent to surface next_steps and the applicable route to the user before mutating. What it lacks is an explicit when-not or a direct comparison to get_projects for listing, so it falls just short of a full routing statement.

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 and closed-world, and the description adds real behavioral context beyond them: the exact response shape, the 100-character truncation of descriptions, and the exclusion of archived projects. These are non-obvious traits an agent would otherwise only discover by calling it.

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, each earning its place: scope first, then return shape and the truncation caveat, then the archived exclusion. No filler and no repetition of the title.

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 spelling out the returned object structure and the truncation limit. Combined with the annotation-covered safety profile, an agent has everything needed to call this correctly and interpret the result.

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 and the baseline applies. It correctly avoids inventing filtering or pagination options that the empty schema does not support.

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 ('List every project stored on this self-host instance') and scopes it to the instance. It also implicitly separates itself from the singular sibling by naming get_project for full records, so an agent can pick between them without opening either 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?

Explicitly routes the agent to the alternative: 'call get_project for the full record' when the truncated description is insufficient. It also states an exclusion rule (archived projects are excluded), which tells the agent when this list is not the right source.

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, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that the payload is the 'full' schema (implying completeness, not a subset), but says nothing about size, format, or whether the schema is static across requests. With annotations doing the heavy lifting, this is adequate but thin.

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 what the tool returns front-loaded before the usage cue. Every clause 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?

For a zero-parameter, read-only introspection tool with full annotation coverage and no output schema, this is nearly complete. The only residual gap is that an agent cannot tell how large the returned schema is or whether it needs to be parsed selectively, but that is minor.

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 no parameter meaning to convey and the schema is trivially complete. Baseline 4 applies; nothing in the description is needed or missing here.

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: fetch the full JSON schema for Ptally project config files. That is clearly distinct from siblings like get_projects or validate_project, though the description never names an alternative such as get_docs, so the boundary with the documentation tool 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?

The second sentence gives concrete usage conditions: check exact field requirements, allowed step types, and property constraints. It lacks any exclusion ('do not use for X, use get_docs instead'), which keeps it off a 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?

Beyond the read-only and idempotent annotations, the description explains what the returned example contains: realistic collection tables, calculations, exclusions, refers, and an embedded tests[] suite. It also clarifies the template-oriented behavior and the catalog behavior when no type is specified.

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 tightly written sentences with no wasted wording. It front-loads the core purpose, then adds useful context about contents and usage, then closes with the catalog 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?

For a low-complexity, read-only tool with two fully documented parameters and no output schema, the description gives an agent enough information about what is returned and how to use it. It covers the starter-project contents and the catalog option without unnecessary detail.

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 already documents both parameters at 100% coverage, including the list/type behavior and the enum values. The description reinforces the no-arguments/list:true catalog behavior but adds little semantic detail beyond the schema, so the baseline of 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 verb and resource: fetch a worked-example Ptally project for a common line of business. It clearly explains that the result is a starter/template project rather than an existing production project, though it does not explicitly distinguish itself from sibling tools such as get_project or get_projects.

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 clear usage context: use the example as a template, copy and adapt it rather than authoring from scratch. It also explains how to get the catalog, but it does not name alternatives or explicitly state when not to use this tool versus sibling project-fetching 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?

Annotations only mark it non-readonly, non-destructive, non-idempotent; the description adds the real behavior: all-or-nothing application, the 200-op cap, refusal of path "", immutability of clipped collections, the 100-row collection limit, and the base_updated_at conflict-refusal. It also states tests are priced after saving and don't block, and that the tool never approves or publishes.

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?

Long but front-loaded and sectioned (BEFORE CALLING, PATHS, EXAMPLES, RULES, RESULT), so an agent can skim to the part it needs. The volume is justified by the addressing complexity, though a few examples and rules could be trimmed without loss.

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 RESULT section fully describes the return shape including saved, updated_at, validation, test counts and failures, plus how to interpret saved: false and conflict errors. For a multi-step mutation tool with intricate path rules, nothing material 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning: paths must be built from the get_project response for that version_reference, base_updated_at must come from that same read or the prior patch's returned value, and version_reference must be latest_draft rather than a published version. Path addressing semantics (id vs index, "-" append, ~0/~1 escaping) are also elaborated 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: change a DRAFT version's stored model via RFC 6902 JSON Patch merged server-side. It distinguishes scope (draft only, never published) and names the sibling tools used around it (get_project, run_version_tests) plus the upload/download path for clipped collections.

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 BEFORE CALLING block gives explicit preconditions and sequencing: resolve latest_draft via get_project, ask the user for approval, then build paths. It also names the alternative (download/upload for __context.patchable: false) and routes test inspection to run_version_tests.

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 declare readOnlyHint=true, which the description substantiates rather than merely repeats: it explains the engine runs but "WITHOUT persisting a quotes row" and returns `dry_run: true` with a null `quote_reference`. It also discloses failure conditions beyond annotations — the version must belong to the project and not be archived, and there is no fallback to drafts, which the agent would otherwise only discover at call time.

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?

It is front-loaded with the action and its persistence semantics, then moves to parameter constraints and the return envelope. The long parenthetical about version_reference is dense and slightly awkward to parse, and the full return-field listing is verbose, though each item is informative rather than 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?

With no output schema, the description carries the return contract and does so by enumerating `output`, `result`, `valid`, `status`, `error`, `errors`, `exec_time_ms`, `dry_run` and `quote_reference`. Combined with the nested-object input caveat and the get_project prerequisite, an agent has everything needed to call it correctly on the first attempt.

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 four parameters are already documented, but the description still adds meaning: the default resolution path for `version_reference` and the hard constraint that an archived or foreign version produces a tool error. It does not explain the optional `source` parameter at all, leaving that one to 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?

"Dry-run a quote against a stored project" names a specific verb (dry-run), resource (quote) and target (project), and the description immediately clarifies that nothing is persisted. An agent can distinguish this from run_version_tests and validate_project without opening any schema, since neither the name nor the text overlaps with those tools' testing/validation framing.

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 prerequisite ("Call get_project first to inspect `input.format` and build a valid input") and states exactly when to supply `version_reference` versus relying on the latest live version. It stops short of naming an alternative tool or an explicit when-not-to-use case, so it is strong context rather than full 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds substantial context beyond that: nothing is persisted, the 0.005 tolerance, that a just-saved patch is included, and the precedence between output and result. Given how much is already in the structured fields, this sits comfortably at 3.

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?

It is front-loaded with the core action and the key usage rules, which is good. But the long inline enumeration of the return shape is dense and hard to parse, and some detail (e.g. the errors cap of 5) could be trimmed or structured. It is informative but not tight.

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 return contract — and it does, covering the fields, the null-passed case, and the problems/errors semantics. Combined with the pass/fail rule and the expected_from precedence, an agent has everything needed to call and interpret this 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 the single version_reference parameter is already documented. The description adds only marginal meaning beyond it: the eligible statuses (any but archived) and the draft-vs-live distinction. With the schema doing the heavy lifting, 3 is the right baseline.

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 opens with a specific verb+resource: prices every test in a version's tests[] against that version's stored model and compares each with its expected output. That is unmistakably distinct from siblings like run_quote, validate_project, and patch_version.

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 names explicit trigger points (after patch_version, after adding or changing tests, before a change to capture a baseline) and states which versions are eligible (any status but archived; draft or live). It also routes the user elsewhere for changing expectations: patch_version on /tests/<test id>/output/result, drafts only.

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 read-only and idempotent annotations, it discloses the result shape and each error's JSON path, keyword, and message, which is especially valuable because there is no output schema. It also states that supplying neither or both inputs returns an error result, and nothing contradicts the 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 result behavior come first, followed by usage guidance and input constraints. Each sentence contributes distinct operational information, and the wording remains efficient without unnecessary repetition.

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 nested two-input validation tool with no output schema, the description covers purpose, alternatives, response contents, input cardinality, mutual exclusivity, and failure behavior. The schema supplies the project structure while get_schema is named for authoring-time validation details, leaving no material invocation 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?

The description adds the exactly-one-of constraint missing from the top-level schema and explains the choice between inline project and base64-gzipped project_gz based on client payload limits. Together with the nested project schema and detailed project_gz schema description, this supplies the semantics needed for correct invocation despite 50% schema coverage.

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

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

The opening sentence identifies the operation, "Server-side schema validation," and the resource, "a project config," narrowing the broader title to schema validation rather than general correctness checking. The comparison with local validation via get_schema also distinguishes it from that sibling.

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 explicitly prefers local get_schema validation during authoring and positions this tool as the ground-truth check, including before returning an amended model to the user. It also specifies when project_gz is appropriate, providing concrete selection guidance for both the tool and its input modes.

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