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

Goes well past the annotations: it explains that documents land as draft (docstatus 0) and need a separate submit via frappe_run_method, that the name is server-assigned by naming series and unknown until return, that validation/mandatory-field/hook checks run atomically so a failure creates nothing, and that create permission on the DocType is required. The 'not idempotent' claim is reinforced by annotation idempotentHint=false and adds the real-world consequence.

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?

Well front-loaded and labelled (Behavior / Parameters / Returns), with each sentence carrying operational content. The trailing Returns line is largely redundant given a full output schema exists, and the restated non-idempotency is a minor duplication.

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 write tool with nested object parameters, the description covers permissions, validation failure modes, naming behavior, draft state, and the follow-up submit path — everything an agent needs to invoke it correctly and interpret the result, even though the output schema already documents the return shape.

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 baseline is 3; the description adds value by stressing fieldnames over form labels and Link fields taking `name` rather than title, and by contributing a detail absent from the schema — omit `name` because the naming series assigns it. Most child-table and mandatory-field guidance duplicates the schema, which keeps it off a 5.

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 — 'Create a new document of the given DocType from the supplied field values' — and immediately distinguishes itself from the sibling frappe_update_doc. An agent can tell what this does and what it does not do 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?

Gives explicit when-to-use ('insert a record that does not yet exist'), the named alternative ('Use frappe_update_doc instead'), and the concrete consequence of misuse (re-running creates a second, separately named document). The submittable-DocType caveat further routes the agent to frappe_run_method when a submit step is needed.

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 flag destructiveHint=true and idempotentHint=false, but the description adds substantial context: no undo or recycle bin, link-exists errors from dependants, cascading child-row removal, the cancel-before-delete rule for submitted documents, and the delete-permission requirement. It also notes the non-idempotent caller experience (second call raises not-found), which is more precise than the annotation alone.

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?

Front-loaded with purpose and the cardinal warning, then cleanly segmented into usage, Behavior, Parameters, and Returns. Slightly long and the Parameters block partially restates schema text, but nearly every sentence carries operational weight.

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?

Covers prerequisites, failure modes, cascade behavior, permission requirements, and batching limits for a two-parameter destructive tool; the return value is briefly noted even though an output schema exists. An agent has everything needed to call this safely.

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 baseline would be 3, but the description adds real semantics: `name` is the primary key rather than a title, a wrong value silently deletes the wrong record, and frappe_get_doc should be used to confirm first. It also reinforces the one-document-per-call constraint, though the field enumerations themselves duplicate 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 ('Permanently delete a document by its doctype and name') plus the irreversible scope. It distinguishes itself from siblings by naming frappe_update_doc and frappe_get_doc with the conditions that select 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?

Gives explicit when-to-use (ToDo, Note, freshly created test records) and when-not-to-use with a concrete alternative ('Prefer frappe_update_doc to set a status such as Cancelled'), listing the transaction types where that applies. 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.

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, yet the description adds real context beyond them: unfiltered state return (draft/submitted/cancelled), role-permission enforcement producing a permission error versus a not-found error, and the {"data": {...}} return shape with nested child tables. That error-semantics disclosure is exactly the kind of value structured fields cannot carry.

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?

Front-loaded with purpose and routing in the first two sentences, then cleanly segmented into Behavior/Parameters/Returns. A few sentences repeat schema content ('case-sensitive and must match Frappe exactly', the Returns block despite an output schema), so it is slightly longer than strictly necessary but never padded.

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

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

For a two-parameter read tool this covers everything an agent needs: selection criteria, sibling routing, error modes, permission behavior, and return shape. An output schema exists, so the description need not explain return values, yet doing so costs nothing and adds no gaps.

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 both parameters are already documented, so the baseline is 3. The description adds genuine meaning on top: that `name` is the list-view primary key rather than a title, and that it only looks human-readable for DocTypes named by field — a distinction the schema does not make. Minor redundancy on case sensitivity keeps it from a 5.

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 ('Retrieve one complete document ... by its exact doctype and document name') and explicitly scopes it to a single DocType record. It also names the sibling it is not (frappe_search_docs) and the computed-value alternative (frappe_run_method), so an agent can distinguish it without reading schemas.

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 positive trigger ('when the document's name is already known, such as SINV-00001') plus three negative conditions that route to frappe_search_docs (find by field value, fetch many, return few fields) and one that routes to frappe_run_method. This is textbook when/when-not/alternatives coverage.

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 destructiveHint=false, but the description adds genuinely new behavioral context: what a pong does and does not prove (reachability/auth yes, per-DocType permission no), and the two failure classes (connection error vs auth error). That is substantive disclosure beyond the structured fields.

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 well front-loaded with purpose and usage before behavior details, and the labeled sections aid scanning. The only waste is the trailing 'Returns: {"message": "pong"},' which duplicates the output schema and could be dropped.

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 diagnostic with rich annotations and an output schema, the description covers everything an agent needs: purpose, routing guidance, what success proves, failure modes, and why no arguments exist. 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?

With zero parameters the baseline is 4, but the description earns the extra point by explaining why there are none — the site and credentials come from the server's environment, 'never from the caller' — and the security consequence that the tool 'cannot be aimed at a different host.' That is meaningful parameter-level context not present in the empty 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 opens with a specific verb and resource: 'Check connectivity and credentials against the configured Frappe/ERPNext site.' It explicitly positions itself against the sibling CRUD tools by calling itself 'a diagnostic, not a data tool,' so an agent can distinguish it 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 states exactly when to reach for it — 'Use first when another tool fails' — and what decision it supports: separating network/credential problems from bad doctype or document names. That is explicit when-to-use guidance tied to the sibling tools' failure modes.

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 flag destructiveHint=true, openWorldHint=true and idempotentHint=false, and the description reinforces rather than merely repeats this: the effect is determined entirely by the named method, it may read/write/delete/enqueue, and calls should be treated as potentially destructive and non-idempotent unless known safe. It adds auth requirements (@frappe.whitelist() decorator, method-level permission checks) and the synchronous 30s FRAPPE_TIMEOUT constraint — exactly the context annotations cannot 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?

Well front-loaded and clearly segmented with 'Behavior:', 'Parameters:', 'Returns:' labels, so an agent can scan for the needed section. The Parameters section largely duplicates the schema text, which is the one place sentences do not fully earn their 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 high-variance, open-world mutation tool this covers what an agent needs: generic dispatch semantics, permission preconditions, timeout behavior, argument-mapping failure modes, and the envelope shape. An output schema exists, yet the one-line 'Returns: {"message": ...}' is a useful, non-wasteful addition.

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 parameter descriptions already state the dotted-path requirement, the exact-signature match for kwargs keys, the error on unknown keys, and the YYYY-MM-DD date convention. The description's 'Parameters:' paragraph restates nearly all of this, only adding the sharper negative framing 'not a DocType method name or a REST path'. Baseline 3 applies when the schema carries the load and the description adds little.

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 ('Call a whitelisted server-side Python method on the Frappe site') and immediately positions itself relative to the CRUD siblings, naming all four by name. An agent can tell from the first two sentences exactly what this tool does and when it is the only option.

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 defines the tool as the 'escape hatch' and gives concrete use cases (submit/cancel documents, run reports, compute stock balances, custom app APIs). It also names the alternatives and the condition selecting them: 'Use frappe_get_doc, frappe_search_docs, frappe_create_doc or frappe_update_doc for ordinary record work' because they validate arguments and describe effects.

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, yet the description adds material context: role-permission filtering means a short result can signal restricted access rather than no matches, and unknown doctype/fieldnames raise errors instead of being ignored. These are non-obvious failure modes an agent could not infer from structured fields.

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?

Front-loaded purpose sentence followed by clearly labeled Behavior/Parameters/Returns blocks is easy to scan. The explicit Returns line is redundant given a real output schema exists, and the parameter paragraph partially duplicates the schema.

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?

Covers routing, permission semantics, error behavior, filter composition limits, pagination strategy, and result shape — everything needed to call a 5-parameter search tool correctly. Nothing material is left to inference.

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?

With 100% schema coverage the baseline is 3; the description adds a concrete pagination recipe (order on `creation`, filter past the last seen value) that the schema's limit text does not give. However, much of the filter/limit/fields text restates the schema descriptions nearly verbatim, so the net addition is modest.

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 or list) and resource (documents of one DocType), plus the scope modifiers (filters, field selection, ordering, pagination). It explicitly distinguishes itself from frappe_get_doc (exact name known) and frappe_run_method (aggregates/reports), so an agent can route without opening schemas.

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 both when-to-use (find by field value, browse a DocType) and when-not-to-use with named alternatives for two distinct cases. The exclusions are concrete conditions, not vague hints.

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 flag write/destructive/idempotent/openWorld; the description adds far more: overwritten values are unrecoverable through this API, DocType validation hooks run and the save is all-or-nothing, submitted documents (docstatus 1) reject edits to fields not marked 'Allow on Submit', and write permission on the DocType is required. This is exactly the behavioural context annotations cannot express.

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?

Front-loaded with purpose and routing, then cleanly sectioned into Behavior, Parameters and Returns. It is on the long side and the Returns line partly duplicates the output schema, but nearly every sentence carries actionable information.

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

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

For a destructive nested-object write tool, the definition covers atomicity, submitted-document constraints, permissions, child-table replacement and field clearing. Nothing an agent needs in order to call it safely is missing, even though the redundant Returns clause could be dropped since an output schema exists.

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 already 100%, so baseline is 3, but the description adds genuinely new semantics: `data` keys are fieldnames not form labels, child-table fields replace the whole table (with a read-then-resend-rows remedy), and fields can only be cleared by explicitly passing null or an empty string. These go beyond the schema text rather than restating it.

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+scope: 'Update selected fields of an existing document, identified by its doctype and name.' It immediately distinguishes partial edit semantics from creation and deletion, so an agent can route correctly 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?

Explicitly names alternatives and the conditions that select them: frappe_create_doc for records that don't exist, and this tool over frappe_delete_doc when a document should be voided while preserving the audit trail. Both the when-to-use and the when-to-prefer-a-different-tool cases are stated.

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