RationalBloks

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds genuine context beyond them: the 500-node ceiling, UNWIND-based performance, and the required per-node shape. However it omits duplicate entity_id handling and what a failure mid-batch does, which matters for a non-idempotent write.

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 the core action and limit in the first sentence, then the use case, then the per-node contract. The worked example is longer than strictly necessary but earns its place by showing the data dict shape.

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 batch mutation tool with rich annotations and full schema coverage but no output schema, the essentials are present. Still missing return-value/error behavior and the consequence of re-submitting an existing entity_id, which an agent needs before bulk-loading.

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 documents all four parameters and the nested node shape; the baseline is 3. The description's example and the '(unique string)' note on entity_id add modest value (uniqueness is not in the schema) but do not substantially extend the parameter 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?

States a specific verb (create), resource (graph nodes), and scope (multiple at once, up to 500 per call). An agent can distinguish it from the single-node sibling create_graph_node and from bulk_create_graph_relationships purely from the description.

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 clear context for when to reach for it ('knowledge graph population — create hundreds of entities from a single book chapter or article') and implies the single-node alternative via 'multiple nodes at once'. No explicit when-not-use or named sibling, so it falls short of 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the write profile is known. The description adds genuinely new operational detail – the 500-relationship ceiling and the Neo4j UNWIND implementation implying a single batched transaction – which the annotations do not cover. It stops short of describing failure/partial-write behavior, which matters for a batch mutation.

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 capability and the 500 limit are front-loaded, and the example is compact and useful. The 'Essential for connecting knowledge' line is mild marketing padding rather than specification, keeping it just short of a 5.

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

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

For a 4-parameter bulk write with full schema coverage and safety annotations already supplied, the description covers semantics, limits, and element shape adequately, and no output schema exists to document. However, with no output schema present, it omits any indication of what a batch creates or returns on partial failure, which is the main remaining 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%, so the baseline is 3, but the description goes further by spelling out the shape of each array element ('from_id, to_id, and optional data') and giving a concrete worked example with real rel_type and property values. It does not clarify environment defaults or that rel_type applies uniformly to every entry beyond what the schema states.

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 ('Create multiple relationships at once') and quantifies scope with a 500-per-call cap, which implicitly separates it from the singular create_graph_relationship and from bulk_create_graph_nodes. It does not explicitly name either sibling, so an agent still has to infer the bulk-vs-single routing.

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?

'Essential for connecting knowledge — link hundreds of concepts, people, and events in one operation' implies the bulk scenario but never states when to prefer this over create_graph_relationship or what to do with fewer relationships. No exclusions or prerequisites (e.g., whether referenced nodes must already exist) are given.

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 write/safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds real context on top: the deployment prerequisite, the schema-matching constraint on entity_type, and meaningful entity_id guidance. It doesn't say what happens on a duplicate entity_id or schema mismatch error, but the added context is substantial.

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-loads the purpose, then REQUIRES, then a worked example – well structured and skimmable. Minor redundancy: 'entity_id is your unique identifier' repeats the schema's own 'Unique identifier for the node' description.

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 single-node creation tool with no output schema, the description covers prerequisites, valid inputs, and an example. It could note error behavior on duplicate IDs or schema mismatch, but nothing essential for a correct call 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 goes beyond the schema by explaining that entity_type must match a project schema entity key, that entity_id is the unique identifier to choose deliberately, and by showing a concrete data example.

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 single node in a deployed graph project') with the scope word 'single' that immediately distinguishes it from bulk_create_graph_nodes. It is also clearly distinct from create_graph_relationship and create_graph_project.

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 concrete prerequisites and routing: project must be deployed, use deploy_graph_staging first, and use get_graph_data_schema to find valid entity types. It stops short of saying when to prefer update_graph_node over create for existing nodes, so it's strong but not exhaustive.

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=false, destructive=false, and openWorld=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the operation is asynchronous (returns a job_id that must be polled for 2-5 minutes) and requires BYOC hosting, plus a retry note when the backend is updating. The retry sentence is garbled but still conveys recovery behavior.

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

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

Despite its length, the content is front-loaded and organized under clear headers (SCHEMA STRUCTURE, FIELD TYPES, RULES, WORKFLOW), and the format detail is arguably necessary for a free-form nested schema parameter. It loses a point for the malformed trailing sentence about RationalBloks, which reads as a truncated fragment.

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 mutation tool with three required parameters and no output schema, the description covers the schema format, deployment prerequisite (register a pool, pass its id), and async follow-up thoroughly. The only gap is that the garbled RationalBloks retry sentence leaves error-handling behavior slightly unclear.

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 would be 3, but the description goes well beyond the schema's one-line 'schema' definition by spelling out the full JSON structure, field types, cardinality options, hierarchical nesting, and naming conventions. This is substantial added meaning for the most complex parameter.

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 states a specific verb and resource: 'Create a new Neo4j graph database project from a hierarchical JSON schema.' The 'graph database project' phrasing distinguishes it from the plain create_project sibling, and the schema-format emphasis makes the intent unambiguous.

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

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

The WORKFLOW block gives explicit ordering and prerequisites: call get_graph_template_schemas first, supply a cluster_id from list_clusters, then poll get_job_status with the returned job_id. This tells the agent exactly when and how to sequence the call relative to siblings.

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 establish the safety profile (not read-only, not idempotent, not destructive). The description adds real behavioral constraints beyond that: the target project must be deployed, rel_type must correspond to a schema key, and both node ids must reference existing nodes. It does not disclose duplicate-handling or failure behavior, which matters given idempotentHint=false.

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 the core action, followed by constraints and a clearly delimited example block. Every sentence earns its place with no 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?

For a mutation tool with no output schema, the description covers prerequisites, schema-key matching, and example payloads, and annotations carry the safety profile. It stops short of describing duplicate/error behavior or the staging-vs-production default, so a small gap remains.

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 schema already documents all six parameters (baseline 3). The worked example supplies added value by showing concrete rel_type, from_id, to_id values and how the nested data object carries relationship properties.

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+resource: 'Create a relationship between two nodes in a deployed graph project,' with scope ('deployed graph project') that narrows intent. It implies the singular counterpart to bulk_create_graph_relationships, though it never names a sibling explicitly.

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

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

Gives clear prerequisites: rel_type must match a project schema relationship key, and it directs the agent to get_graph_data_schema to discover valid types. It does not contrast with the bulk variant or create_graph_node, so routing guidance is incomplete.

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, so the safety profile is covered. The description adds important behavioral detail beyond annotations: this is a DETACH DELETE that also removes every connected relationship, clarifying the blast radius. It does not cover permission requirements or irreversibility confirmation.

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, front-loaded with the destructive scope. The warning symbol and parenthetical 'DETACH DELETE' earn their place without 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?

For a destructive mutation with no output schema, the description plus annotations give enough to call it safely: it names the cascade deletion and the deployed-graph context. It omits environment default/impact (staging vs production) and return behavior, but those are minor given the schema and destructive annotation.

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 all four parameters (project_id, entity_type, entity_id, environment) are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, 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?

Specific verb 'Delete' + resource 'node' + cascade scope 'all its relationships' + environment 'deployed graph project'. The scope statement distinguishes it from sibling delete_graph_relationship (relationship only) without needing to name it.

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?

No explicit when-to-use context, prerequisites, or alternative routing. It does not tell the agent when to choose this over delete_graph_relationship, update_graph_node, or delete_graph_project, nor when not to delete.

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?

Goes well beyond the annotations. Annotations only declare destructive/non-idempotent; the description discloses exactly what is destroyed, that execution is asynchronous with a job_id to poll, the single-operation-per-project lock and its refusal semantics (naming the running job), and a transient refusal during platform updates.

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, each carrying distinct operational value (scope of deletion, async polling, concurrency/update-window retries). Front-loaded with the destructive scope before the coordination mechanics, with 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 destructive, one-parameter tool with no output schema, everything an agent needs is present: what gets removed, that the result is a job_id, how to poll it, and how refusals behave. No important gap remains.

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

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

Only one parameter (project_id) with 100% schema description coverage, so the schema already documents it fully. The description adds no format or constraint detail about project_id beyond what the schema provides, 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?

States a specific verb (Delete) and resource (graph project), and immediately enumerates the downstream assets removed (GitHub repo, K8s deployments, Neo4j database, credentials). This scope makes it readily distinguishable from siblings like delete_project or rollback_graph_project.

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 strong operational guidance: it runs as a job and must be polled via get_job_status, one operation per project at a time, and retry behavior during RationalBloks updates. It does not explicitly contrast itself against sibling alternatives such as delete_project or rollback_graph_project, but the when/how guidance is concrete.

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 destructiveHint=true, so the irreversible nature is covered by structured data. The description adds only the internal-ID scoping detail; it does not mention cascade effects on related nodes, permission requirements, or whether the relationship's node endpoints are affected.

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: the action and its scope come first, followed by the ID-discovery hint. Nothing is padded and no sentence 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?

For a destructive mutation with no output schema, the description tells the agent what to delete but not what happens afterward, what errors to expect, or how environment (staging vs production) affects the operation. Annotations carry the safety profile, but behavioral completeness is only minimally adequate.

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 every parameter including environment and rel_type documented in the schema itself, so the baseline is 3. The description's mention of 'internal ID' merely restates the schema's rel_id description without adding format or constraint detail.

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 ('Delete a specific relationship by its internal ID'), which naturally separates it from delete_graph_node and delete_graph_project. However, it never explicitly names or differentiates against those siblings, so an agent must infer the distinction from the resource noun alone.

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 pointer to get_node_relationships for obtaining IDs is useful usage context, but it is a how-to, not a when-to-use: there is no statement of prerequisites (e.g., environment/deployment state), no exclusion cases, and no routing advice versus delete_graph_node.

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 destructiveHint=true and non-idempotent, but the description goes well beyond them: it names what is destroyed (pods, project membership, CORS origins), discloses the concurrency lock, quotes the exact refusal messages, and prescribes retry timing. This is unusually rich behavioral context for a destructive tool.

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 with no filler: the effect is front-loaded, the DESTRUCTIVE marker is prominent, and the concurrency and retry rules follow in priority order. Every clause carries operational 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 one-parameter destructive tool with no output schema, the description covers the effects, the safety profile, the failure modes, exact error text, and the recovery path. An agent has everything needed to call it correctly and to handle refusals.

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 module_id parameter is already documented in the schema with a pointer to list_modules. The description adds no further syntax, format, or sourcing detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Remove) and resource (module) and immediately enumerates the observable consequences: pods stop, it leaves the project, its CORS origins are cleaned up. This distinguishes it from the many delete_* and delete_graph_* siblings at a glance.

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 clear operating conditions: only one operation per module at a time, the refusal names the running job, wait via get_job_status then retry, and retry during platform updates. It routes to the get_job_status sibling explicitly, though it does not contrast against non-destructive alternatives such as freeze_module or delete_project.

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

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

Annotations only declare a destructive write profile, but the description adds the async job model, the polling requirement, single-operation concurrency, the exact refusal semantics, and the multi-system destructive scope. It also implicitly confirms non-idempotency (refusals, re-invocation) consistent with idempotentHint=false.

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 sentences, each load-bearing: scope, async contract, concurrency contract, outage contract. Ordered from what it does to how to drive it, with no restatement of the name or 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?

With no output schema, the description supplies the missing return contract (a job_id) and the polling loop needed to consume it, plus the failure modes an agent must handle. Nothing required to invoke and complete this operation is left unstated.

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 one parameter and schema description coverage is 100%, so the schema already documents project_id as a UUID. The description contributes no additional parameter meaning, which matches the baseline of 3 when the schema carries the load.

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 plus the exact blast radius (GitHub repo, K8s deployments, database), which immediately distinguishes it from delete_graph_project, delete_module, and drop_schema_items. An agent can select it without opening any sibling 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 prescribes the follow-up pattern (poll returned job_id with get_job_status) and the two refusal conditions with their remedies: concurrency lockout names the running job and says to wait, and the RationalBloks update window says to retry in a few minutes. This is when/when-not guidance with the alternative tool named.

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 goes well beyond them: it names exactly what loses data (tables, fields, entities, relationships), discloses async behavior with job_id polling via get_job_status, and documents both refusal modes (concurrent operation naming the running job, and RationalBloks maintenance). This is the burden-carrying detail an agent needs before an irreversible call.

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-loads the destructive warning and the intent condition, then handles async, concurrency, and maintenance in discrete, scannable statements. It is long, but nearly every clause carries an operational constraint; only the environment restatement 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?

With no output schema, the description still covers the return contract (poll job_id with get_job_status) and the failure paths. For a two-parameter destructive mutation tool, an agent has everything needed to decide, invoke, and follow up 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 both parameters are already documented in the schema. The description's restatement of the environment values (staging deploys the saved schema, production promotes staging) mirrors the schema text rather than adding new meaning, 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?

States a specific verb ('Deploy a plan that drops data') plus scope ('relational or a graph project'), and the title/description immediately distinguish it from the non-destructive deploy siblings. An agent can tell this apart from deploy_staging/deploy_production 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?

Explicit when-to-use: only after a deploy tool (deploy_staging, deploy_production, deploy_graph_staging, deploy_graph_production) refused the plan, naming its drops, and those drops are intended. It also names the environment semantics and the concurrency/maintenance refusals to expect. 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 only cover the coarsest safety flags; the description goes far beyond them, disclosing refusal semantics (destructive plans are refused with a full enumeration of dropped items and lossy type changes), single-operation-per-project serialization, and the literal maintenance error string. This is exactly the behavioral context annotations 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 the core action and effect before the long tail of refusal cases. Dense and mostly earned, though the final maintenance-retry sentence is somewhat verbose and could be tighter without losing meaning.

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 deployment tool with no output schema, the description covers what an agent needs: prerequisites, the destructive-plan escape hatch, concurrency limits, and retry triggers with the exact tool to poll. 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?

One parameter with 100% schema description coverage ('Project ID (UUID)'), so the schema already carries the semantics. The description adds nothing parameter-specific, which is the expected baseline when the schema does the work.

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 ('Promote graph staging to production') and immediately clarifies the effect: a separate production Neo4j instance with its own credentials and database. This clearly distinguishes it from deploy_graph_staging and deploy_production.

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 states prerequisites (requires paid plan), routes dropping plans to the sibling deploy_destructive, and gives the exact when-to-retry conditions (concurrent job → wait via get_job_status then call again; maintenance window → retry in a few minutes). 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 only declare the safety profile (not read-only, not destructive, not idempotent). The description adds far more: async execution with a job_id, 2-5 minute duration, single-operation concurrency locking with a named refusal, and the data-loss refusal semantics. This is rich context beyond structured data.

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 the core purpose and numbered steps, then operational guidance. Dense but mostly earned; the long data-drop refusal clause is valuable but slightly verbose compared to the sharper concurrency and refusal notes.

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, yet the description explains the return (job_id), timing, monitoring path, and verification path, plus failure and refusal modes. An agent has everything needed to invoke and follow up 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 project_id parameter is fully documented in the schema, so the description need not carry it. The description refers to a 'graph project's saved schema' but adds no format or constraint detail beyond the schema's 'Project ID (UUID)'. Baseline 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?

Precise verb+resource+target: 'Deploy a graph project's saved schema to the staging environment.' It enumerates the five concrete steps performed and clearly distinguishes itself from deploy_graph_production and deploy_destructive, which it names 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?

Explicit routing: use deploy_destructive instead when the plan drops data, use get_job_status to monitor, use get_graph_project_info to verify success. It also states when the call is refused (concurrent job, RationalBloks update) and what to do about it, leaving nothing 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?

Adds substantial behavior beyond annotations: async execution requiring get_job_status polling, the 'RationalBloks is being updated' refusal and retry advice, CORS origin integration, private-repo GitHub App requirement, and port 8000/GET /health for logicblok. This is rich context the annotations (non-idempotent, non-destructive) 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?

Dense and front-loaded, with the core deploy action and module types stated first and the async/polling caveat last. Slightly overpacked with detail (port, health endpoint) but every sentence carries operational value.

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, yet the description names the returned job_id and the follow-up tool, and covers auth requirements, retry behavior, and module-type semantics. Nothing critical for a correct invocation 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%, so the schema already documents all 9 parameters. The description clarifies module_type semantics and git_ref's default-branch behavior, but adds little beyond what the schema states; baseline 3 applies.

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

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

States a specific verb+resource ('Deploy a new module from a GitHub repository onto the project's resource pool') and defines both module types, distinguishing it from redeploy_module which operates on existing modules. An agent can identify the operation 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?

Implies this is for creating a new module and explicitly routes polling to get_job_status. However, it never names redeploy_module as the alternative for an existing module, so the create-vs-redeploy boundary 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?

The description carries the full behavioral load beyond the annotations: it discloses the ASYNCHRONOUS nature and job_id polling, the one-operation-per-project lock with a refusal naming the running job, the RationalBloks maintenance refusal, and how a destructive plan is refused and deferred to another tool. These are real traits not expressed in the annotation flags.

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 the core async/polling behavior are front-loaded, and every sentence carries operational detail. The long parenthesized clauses and dense run-on sentences slightly reduce readability, but little 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?

With no output schema, the description still explains the return contract (job_id) and the exact failure/refusal semantics an agent must handle. Nothing an agent needs to invoke or recover 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?

Only one parameter exists and the schema documents it at 100% coverage (UUID), so the baseline is 3. The description adds no format or constraint detail about project_id beyond what the schema already states.

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 ('Promote staging to production') and immediately scopes it ('requires a paid plan'). It is clearly distinguishable from siblings like deploy_staging, deploy_graph_production, and deploy_destructive 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?

Explicitly routes to alternatives: poll with get_job_status, and use deploy_destructive when a plan would drop data. It also names the refusal conditions (concurrent operation, RationalBloks update) and prescribes the recovery action for each.

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 give readOnlyHint=false/destructiveHint=false/idempotentHint=false; the description adds the async contract, the returned job_id, a 2-5 minute duration, the one-operation-per-project lock with a named refusal, the maintenance-window refusal, and the fact that data-dropping plans are refused here and handled by deploy_destructive. No description content conflicts with the destructiveHint=false annotation.

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 the core action and async contract, and nearly every sentence carries behavioral or routing value. It is dense and includes a few run-on sentences (the destructive-plan explanation names many sub-cases), which slightly hurts readability, but there is little genuine waste.

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 compensates fully: it explains that the call returns immediately with a job_id, how to poll progress, how long it takes, and how to interpret success or failure. Everything an agent needs to invoke and follow through is present.

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% (project_id documented as 'Project ID (UUID)'), so the schema already carries the parameter meaning. The description adds nothing about the single parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Deploy a project's saved schema to the staging environment') and enumerates the five pipeline steps the operation triggers. It also names the sibling it is not ('deploy_destructive applies it, a tool of its own'), letting an agent route destructive plans elsewhere without opening a 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 follow-up work: use get_job_status with the returned job_id to monitor, use get_project_info to confirm success, retry later when a concurrency or maintenance refusal occurs. It even explains when to read a job error versus when to fix the schema, which is more than most definitions offer.

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, but the description goes well beyond them: it warns the next deploy drops their data, documents all-or-nothing atomicity ('refuses them all, naming it, and nothing is saved'), and discloses the 409 refusal on a stale expected_version. It also names the response fields ('applied', 'diff', 'plan', 'version') that no output schema provides.

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 destructive warning is front-loaded, then operations, then refusal behavior, then workflow, each as a distinct labeled block. It is longer than a one-liner but no sentence is redundant against the annotations or 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?

For a destructive mutation with no output schema, the description supplies the missing return-value information, the atomicity guarantees, the failure mode, and the surrounding workflow. Nothing an agent needs to invoke it safely and correctly is absent.

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, but the description lifts it by giving concrete operation payloads (drop_table/drop_field JSON examples) and by restating the atomic in-order application and the expected_version refusal semantics. This adds usable format detail beyond the schema's generic 'items: object'.

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 ('Drop tables or fields from a project's saved schema') and immediately disambiguates scope with '(saves to database, does NOT deploy)', separating it from the deploy_* siblings. An agent can distinguish it from patch_schema, update_schema, and deploy_destructive 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?

Provides an explicit numbered workflow (preview_schema_change -> drop_schema_items -> deploy_staging/deploy_destructive -> get_job_status) that names the alternatives and the condition selecting each one. It also states when to pass expected_version and what happens if someone else saved meanwhile.

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?

Goes well beyond the annotations: annotations only declare non-read-only, idempotent, non-destructive, closed-world. The description adds the actual mechanism (scale to 0 with replica count remembered), the concurrency lock semantics, the exact refusal behavior ('the refusal names the running job'), the recovery tool, and a maintenance-window refusal with a retry instruction. This is rich, actionable behavioral context.

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-loads the core action and its inverse in the first clause, then layers on constraints and recovery steps in a logical order. Dense but every sentence carries distinct operational value; the quoted maintenance message is slightly verbose but directly usable.

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 mutating operation with concurrency and maintenance-window failure modes and no output schema, the description supplies everything needed to call it correctly: effect, idempotency, lock behavior, error handling, and retry timing. Nothing material is left for the agent to infer.

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, module_id, and schema description coverage is 100% ('Module ID (list_modules)'). The description adds no syntax or format meaning beyond what the schema already states, so the baseline of 3 for high coverage applies.

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

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

States a specific verb and resource with the exact mechanism: 'Stop a module's pods (scale to 0), remembering how many it ran.' It further disambiguates by naming the inverse sibling unfreeze_module, so an agent can tell freeze from unfreeze and from scale_module 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?

Explicitly covers when the call is a no-op ('Freezing a frozen module changes nothing'), the concurrency constraint (one operation per module, none alongside a project operation), and the alternative action when refused (wait via get_job_status, then retry). It names a sibling tool and routes the agent correctly.

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 and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: it searches every text field, returns _match_fields identifying matching properties, and provides a concrete example. This goes beyond annotations without contradicting them.

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 concise and front-loaded: the first sentence states the core function, followed by a contrast, a use-case, an example, and an optional filter note. Every sentence adds value, and there is no redundancy or 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 read-only search tool with 6 parameters all described in the schema, the description covers the essential return behavior (_match_fields) and the key differentiating feature. It lacks explicit pagination/limit caveats, but those are already in the schema, and the 'deployed graph' context plus the search scope make it sufficiently complete for an agent to select and invoke 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. The description adds semantic value by clarifying that 'query' searches across all string properties with an example listing possible fields, and mentions the 'entity_type' filter. This supplements the schema's terse parameter descriptions with context on how the query behaves.

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: 'Search across ALL string properties of ALL nodes in a deployed graph using free-text queries.' It clearly distinguishes itself from the sibling 'search_graph_nodes' by explicitly contrasting behavior, making the tool's purpose unmistakable.

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 guidance is explicit: 'Perfect for finding knowledge when you don't know which property contains the answer' and names the alternative (search_graph_nodes) with its limitation. This provides clear when-to-use and when-not-to-use direction, exceeding basic 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?

Annotations already declare the tool as read-only and idempotent. The description adds value by detailing the return contents (entity keys and relationship keys) and clarifying that the schema is from a deployed project. This goes beyond the annotations without contradicting them.

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 concise and well-structured: a clear one-sentence summary, a returns line, and a highlighted usage tip. Every sentence provides distinct value with no repetition or fluff.

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

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

For a simple read-only schema lookup tool with no output schema, the description covers the essential information: what the tool does, what it returns, and when to use it. Minor gaps exist (e.g., behavior if project is not deployed), but overall it is sufficiently complete given the tool's simplicity.

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 input schema already documents both parameters with descriptions (project_id, environment) at 100% coverage. The description does not add extra parameter-level details beyond the schema, but it does imply the project must be deployed, which is contextual. Baseline 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 clearly states the tool's function: 'Get the runtime schema of a DEPLOYED graph project' and specifies what it returns (entity types and relationship types). This distinguishes it from sibling tools like get_graph_schema or get_graph_schema_at_version by emphasizing the runtime/deployed aspect and its purpose for data operations.

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 provides clear usage context: 'USE THIS FIRST before creating nodes/relationships' and explains that it helps identify valid entity_type and rel_type values. It does not explicitly name when not to use it or alternatives, but the contextual guidance is strong enough for most use cases.

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 behavior. The description goes beyond annotations by stating it returns all node properties including created_at/updated_at timestamps and only works on deployed graph projects, which adds useful behavioral context without contradicting 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?

The description is two sentences, front-loaded with the primary purpose and a concise summary of return value. Every word earns its place, with no redundancy or 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 simple get-by-id tool, the description covers the action, return content, and a deployment prerequisite, which partially compensates for the lack of an output schema. Minor gaps around error handling and entity_type semantics exist, but overall it is sufficiently complete for an agent to invoke 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 descriptions cover 100% of parameters, so the baseline is 3. The description adds minimal parameter-related detail beyond restating entity_id and the notion of a deployed project; it does not explain environment behavior or entity_type nuances, so no higher score is warranted.

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 tool retrieves a specific node by entity_id from a deployed graph project, which is a distinct action from sibling tools like list_graph_nodes or search_graph_nodes. It also specifies what is returned (all node properties with timestamps), fully clarifying its purpose.

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 conveys the specific use case of fetching a single node by entity_id from a deployed project, providing clear context. However, it does not explicitly contrast with alternatives such as list_graph_nodes or get_node_relationships, so it stops short of full when-not 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 destructiveHint=false, covering the safety profile. The description adds value by disclosing what information is retrieved (deployment status, database health, pod status, resource usage), which is useful behavioral context beyond the annotations. No contradiction.

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 two sentences, front-loaded with the purpose in the first sentence and usage guidance in the second. Every sentence earns its place, with no filler or 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?

The tool has one parameter, no output schema, and annotations covering safety. The description explains what data is included and when to use it, which is sufficient for an agent to select and invoke the tool. It doesn't describe the return format, but that is not required given the lack of an output schema and the straightforward nature of the 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?

The input schema has 100% coverage with the parameter project_id described as 'Project ID (UUID)'. The description does not add any additional meaning to the parameter, so the baseline of 3 is appropriate given the high 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 description clearly states the tool's purpose: 'Get detailed graph project information' and specifies the scope with concrete details (Kubernetes deployment status, Neo4j database health, pod status, resource usage). This verb+resource structure distinguishes it from siblings like get_project_info or get_graph_statistics.

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 provides clear context: 'Use this after deployment to verify the graph project is running correctly.' This tells the agent when to use it, though it doesn't explicitly mention when not to use it or name alternative tools. This fits 'clear context, no exclusions' at level 4.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds genuinely useful behavioral context beyond that: the semantics of saved_schema_deployed across all three states (true/false/null) and the meaning of undeployed_changes. This is valuable return-behavior disclosure that neither the schema nor annotations provide.

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, well front-loaded: the core action first, then the format distinction, then the deploy-status semantics. The second sentence partially restates the first (nodes/entities/relationships appear in both), so it is not maximally lean, but each sentence still carries meaningful 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 single-parameter, read-only getter with full schema coverage and safety annotations, the description is nearly complete: it explains what is returned, how graph schemas differ from relational flat-table schemas, and the semantics of the deploy-status field. The only gap is not pointing to version-history or template siblings, which is a nice-to-have rather than a correctness issue.

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% — project_id is already documented as a UUID string. The description adds no parameter-level detail beyond 'of a project,' which merely echoes the schema. With full schema coverage, baseline 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?

Opens with a specific verb+resource: 'Get the graph schema definition of a project.' The description then specifies the return shape (hierarchical schema with nodes/relationships) and explicitly contrasts it with relational flat-table schemas, distinguishing it from siblings like get_schema. The tool's purpose is unambiguous and differentiated.

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?

Provides clear context that this retrieves the hierarchical graph-schema format rather than a relational flat-table schema, which helps an agent choose between get_graph_schema and get_schema. However, it never names sibling alternatives such as get_graph_schema_at_version or get_graph_template_schemas, and gives no explicit when-not guidance for those cases.

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 provide readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to restate safety. It adds meaningful context by specifying that the tool returns the schema as it existed at a specific version, which is a key behavioral trait beyond annotations. It also hints at dependencies (version history lookup).

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 two concise sentences. The first sentence states the core purpose, and the second adds a pointer and use cases. No redundant content or filler words are present.

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

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

For a simple read-only tool with two parameters and strong annotations, the description provides sufficient context: it clearly states what the tool does, how to obtain the required version value, and typical use cases. The lack of an output schema is acceptable given the simple nature of the operation.

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 baseline is 3. The description adds value by clarifying that 'version' is a commit SHA and pointing to get_graph_version_history to obtain it, which is not explicitly stated in the schema's property description. This helps the agent understand how to populate the required parameter.

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 'Get the graph schema as it existed at a specific version/commit' with a specific verb and resource, and explicitly differentiates from current-schema retrieval by emphasizing the historical aspect. It also references get_graph_version_history for finding commit SHAs, further distinguishing it from sibling tools like get_graph_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?

The description explicitly directs users to get_graph_version_history to find commit SHAs and names usage scenarios ('comparing schemas across versions or auditing changes'). However, it does not provide explicit when-not-to-use guidance or mention the alternative for current schema (e.g., get_graph_schema), so it falls short of 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the 'deployed graph' qualifier and the specific statistics returned, but does not discuss response format, pagination, or other behavioral details beyond what annotations provide.

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 one concise, front-loaded sentence listing the metrics, followed by a brief value sentence. Every word earns its place; no fluff or 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?

Given the absence of an output schema, the description compensates by explicitly listing the returned statistics (node count, relationship count, per-type counts) and a practical use case. It does not detail the response shape, but for a simple statistics tool, this is reasonably complete.

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

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

Schema description coverage is 100%, with both parameters (project_id and environment) fully described. The tool description does not add any parameter-level detail beyond what the schema already provides, so the baseline score 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 clearly states it retrieves statistics about a deployed graph, enumerating specific metrics (node count, relationship count, counts per entity/relationship type). This distinguishes it from sibling tools like get_graph_schema or get_graph_node.

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 gives a clear context: 'Essential for understanding the current state of a knowledge graph before adding more data.' It does not explicitly list alternatives or exclusions, but the intended use case is well communicated.

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, so the safety profile is covered. The description adds value by detailing the internal structure of the templates (node definitions, relationship configs) and noting they can be used as-is or adapted for create_graph_project. No contradictions with annotations.

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

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

The description is slightly long but front-loaded with the most critical instruction (USE THIS FIRST). Each sentence contributes: template list, structure explanation, and usage tip. The TIP and explicit template examples justify the length for a tool that needs to convey format details.

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 tool with no output schema, the description fully covers what is returned (list of templates and their structure), when to use it, and how to apply the output. Nothing essential 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?

There are zero parameters, so the baseline is 4. The description appropriately compensates by explaining what the tool returns and how to interpret the template data, even though no input parameters need documentation.

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 ('Get') and resource ('pre-built graph template schemas'), lists concrete templates, and explicitly marks it as the first step for creating a new graph project. This clearly differentiates it from sibling tools like get_template_schemas (non-graph) and get_graph_schema (retrieves existing 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?

It gives explicit when-to-use guidance ('USE THIS FIRST when creating a new graph project') and explains how the output feeds into create_graph_project. However, it does not explicitly contrast with alternatives such as get_template_schemas or other schema-related tools, leaving some inference to the agent.

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 and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by detailing exactly what the history includes (commit SHAs, timestamps, version numbers, messages) and framing it as 'deployment and version history,' which goes beyond the minimal read-only disclosure. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the primary action and resource, followed by a concise list of returned details and a clear use case. Every sentence adds value; there is no waste.

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

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

For a simple read-only tool with one parameter, the description is complete: it states the purpose, the exact return content (schema changes, commit SHAs, timestamps, version numbers, messages), and the intended use case. Since there is no output schema, the description effectively covers what the agent needs to know.

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 input schema already fully documents the single parameter (project_id with description 'Project ID (UUID)'), so schema coverage is 100%. The description adds no additional meaning about the parameter beyond what the schema provides. Baseline of 3 is appropriate since the description does not need to compensate.

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 uses a specific verb ('Get') and resource ('deployment and version history for a graph project'), clearly distinguishing it from the generic sibling get_version_history. It also specifies the content (schema changes, commit SHAs, timestamps, version numbers, messages), leaving no ambiguity about what the tool does.

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 explicitly states when to use the tool: 'Use this to find a specific version for rollback operations.' This gives clear context for usage, though it does not explicitly mention alternatives or when not to use it. The context is strong enough to guide an agent to this tool over siblings like rollback_graph_project or get_graph_schema_at_version.

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 cover the read-only/idempotent safety profile; the description adds the operationally critical context an agent cannot infer — status value vocabulary, expected completion windows, and how to interpret failure_side/error ('customer' means the project input is provably at fault and says what to change; 'platform' means escalate rather than edit the schema). That is exactly the extra behavioral depth the dimension asks for.

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-loads the purpose, then blocks of STATUS VALUES and failure handling — well ordered and free of filler. Some sentences are long compound constructions that could be split, but each clause carries distinct 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?

No output schema exists, yet the description names the return-relevant fields (status values, failure_side, error, module_code, image/commit) often enough that an agent can act on a response without guessing. Combined with polling cadence and failure triage, nothing needed to call this 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 coverage is 100% for the single parameter, so baseline is 3; the description adds value by tying the id's origin to concrete operation types and by explaining what the corresponding job reports back (module_code, built image/commit). It stops short of format or reuse constraints on job_id.

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 ('Check the status of a job') and immediately enumerates which job kinds qualify (create, deploy, promotion, rollback, deletion, module). This separates it cleanly from the sibling list_project_jobs, which enumerates rather than polls a single job.

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 polling guidance: 'Call it until the status is completed or failed,' plus termination reasoning (every job ends; stalled server => failed in ~3 min; deploy up to 15 min). It never names list_project_jobs as the alternative for enumerating jobs, so the when-not side is only implied.

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 destructiveHint=false, so the safety profile is known. The description adds little extra behavioral context beyond repeating the filtering options already present in the schema. It doesn't mention pagination, return shape, or any other behavioral traits.

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 two concise sentences, front-loaded with the primary action and then listing the core filtering options. There is no redundancy or 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 read-only query tool with full schema coverage and safe annotations, the description is largely complete. However, since there is no output schema, a brief note about the returned relationship objects or pagination behavior would enhance completeness.

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 all parameters already have meaningful descriptions. The tool description mentions direction and relationship type filtering but only restates what the schema provides, adding no new semantic information.

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 tool fetches all relationships connected to a specific node, using a specific verb ('Get') and resource ('node relationships'). It also mentions the key filtering options (direction and relationship type), which distinguishes it from sibling tools like traverse_graph or search_graph_nodes.

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 implies when to use this tool (when you need relationships for a node) but provides no explicit comparison to alternatives. With sibling tools like traverse_graph and search_graph_nodes available, more explicit guidance on when to choose this over them would be beneficial, but the core use case 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?

The annotations already mark this as read-only, idempotent, and non-destructive, and the description is consistent with that. The description adds no additional behavioral context beyond the annotations, such as response format or access requirements.

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

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

The description is a single, clear sentence that is appropriately concise and front-loaded with the action and resource. There is no unnecessary wording.

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?

As a simple read operation with full schema coverage and strong annotations, the description is adequate but leaves ambiguity about what 'detailed information' includes, especially given the existence of 'get_project_info'. Without an output schema, the agent cannot know the exact response 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?

The input schema fully describes the only parameter, 'project_id', including its type and format. The description adds no further explanation about the parameter's meaning or restrictions.

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 tool retrieves detailed information about a specific project. However, it does not distinguish itself from the similarly named sibling tool 'get_project_info', so it lacks sibling differentiation.

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 provides no guidance on when to use this tool over alternatives such as 'get_project_info' or 'list_projects'. No usage context or exclusions are given.

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 mark the tool as read-only and idempotent, but the description adds substantial behavioral detail beyond them: exact deployment statuses, failure interpretations, troubleshooting steps, and the fact that staging.url/production.url/github.url are returned. It also reveals that create_project lacks URL return, which clarifies this tool's unique value. No contradiction with annotations.

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

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

The description is longer than average but every sentence earns its place: purpose, statuses, troubleshooting, return-value behavior, and when-to-use guidance. It is front-loaded with the core purpose and uses clear section labels (DEPLOYMENT STATUS, TROUBLESHOOTING, RETURNS) that make it easily scannable for an agent.

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 there is no output schema, the description compensates by explaining key return fields (staging.url, production.url, github.url) and covering status semantics and failure diagnostics. The tool has a single required parameter, and the description gives enough context for an agent to call it 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?

Schema description coverage is 100% for the single parameter project_id, which is already documented as a UUID. The description does not add parameter-specific meaning beyond what the schema provides, but it doesn't need to; the baseline of 3 applies since the schema carries the full parameter information.

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: 'Get detailed project info including deployment status and resource usage.' It clearly distinguishes from create_project by noting that create_project does NOT return a URL and that this tool is the one to call after deployment. The scope is concrete and unambiguous.

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

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

The description explicitly states when to use this tool: 'create_project does NOT return a URL, so this is the tool to call once get_job_status reports the deployment finished.' It also guides troubleshooting by directing the agent to 'Use get_schema to review current schema' when CrashLoopBackOff occurs. This is clear usage guidance with named alternatives.

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 destructiveHint=false, so the safety profile is established. The description adds useful return-value context ('file count and bytes used against the plan limits') but does not disclose additional behavioral traits such as how usage is calculated, whether deleted files are included, or any rate 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 a single, dense sentence that front-loads the core purpose and the key return metrics. Every word contributes useful information, with no repetition of schema details or annotations.

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, two-parameter tool with no output schema, the description adequately conveys the main return values (file count and bytes used vs. plan limits). It could be slightly more complete by noting whether plan limits themselves are included in the response, but it does not leave an agent without essential calling context.

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 parameters (project_id and environment) are already fully documented in the input schema. The description adds no parameter-specific detail beyond mentioning 'a project,' 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 clear verb and resource: 'Get object-storage usage for a project,' and specifies the exact metrics returned ('file count and bytes used against the plan limits'). This distinguishes it from siblings like get_project_usage, which is broader, and list_project_files, which lists files rather than usage totals.

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 clearly implies when to use the tool: when you need object-storage usage metrics such as file count and bytes consumed relative to plan limits. It does not explicitly name alternatives or exclusion criteria, but the object-storage qualifier provides enough context to differentiate it from related project-level 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no extra behavioral context such as permissions, time-range constraints, or rate limits, offering nothing beyond what structured data already indicates.

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

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

The description is a single, focused sentence that immediately conveys the action, resource, and scope. Every word contributes meaning with no fluff or repetition of the tool name.

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 simple with one well-documented parameter and good annotations, so the description is mostly sufficient. However, there is no output schema and the description omits details like whether metrics are real-time, units, or response format, leaving some ambiguity for an agent. It is minimally complete but not rich.

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% with a clear description for project_id ('Project ID (UUID)'). The description only says 'for a project', which adds no additional meaning beyond the schema, so the baseline score 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 clearly states the verb 'Get' and the specific resource ('resource usage metrics (CPU, memory)') for a project, making it distinct from sibling tools like get_project or get_graph_statistics. It precisely answers what the tool does.

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 implies the tool should be used when needing CPU/memory usage for a project, but it does not explicitly state alternatives or when not to use it. There is no comparison to sibling get_* tools, but the usage scenario is reasonably inferable.

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 behavior, and the description adds materially: the FLAT representation, saved_schema_deployed tri-state semantics, undeployed_changes behavior, and the fact that version is whole-schema even when a slice is requested. This goes well beyond what annotations alone 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?

The description is front-loaded with purpose and format, then moves to use cases, response semantics, and large-schema guidance – all valuable. Some redundancy ('FLAT format' stated twice, a four-item use-case list that partly overlaps) keeps it from a 5.

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

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

Without an output schema, the description carries the burden of explaining return values, and it does: schema object shape, saved_schema_deployed, undeployed_changes, and version semantics. For a 3-parameter read-only tool, nothing necessary to call it correctly is missing.

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

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

Input schema covers each parameter at 100%, so baseline is 3. The description adds strategic meaning for tables/fields: slice the schema for large projects, and any slice's version remains the whole schema's version, which is enough to feed patch_schema. That is meaning the schema descriptions do not provide.

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 an exact verb+resource ('get the JSON schema definition of a project in FLAT format') and explains the output shape, so an agent knows what operation this is. It is less explicit than ideal at differentiating from siblings like get_schema_at_version or get_graph_schema: it implies 'current/saved' schema but never names the alternatives.

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?

Four explicit use cases (review before updates, copy as template, verify after deploy, learn by example) tell the agent when to invoke this tool. It does not give exclusions or mention alternatives such as get_schema_at_version for historical schemas, so it misses the top of the scale.

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, covering safety. The description adds the behavioral fact that the returned schema is a historical snapshot, but does not disclose return format, permissions, or other side effects. With annotations present, this is adequate 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?

The description is a single sentence of 10 words, front-loading the verb and purpose with no fluff. Every word 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 simple read-only tool with two fully documented parameters and robust annotations, the description is adequate. It could benefit from a note about using get_schema for the current version, but overall it is complete for its complexity.

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 input schema covers both parameters fully (100%): version as commit SHA, project_id as UUID. The description adds no additional parameter semantics beyond the schema, so the baseline of 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 clearly states the tool retrieves the schema as it existed at a specific commit, using a specific verb (get), resource (schema), and temporal scope (at a version/commit). This distinguishes it from sibling tools like get_schema (current schema) and get_version_history (history listing).

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 implies usage for retrieving historical schema snapshots, providing clear context. However, it does not explicitly mention exclusions or alternative tools for current schema, so it stops short of 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by indicating the tool returns subscription tier, limits, and usage, which gives a clue about the response contents. However, it does not disclose any other behavioral traits such as error conditions or auth requirements.

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

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

The description is a single, tightly written sentence that front-loads the action ('Get') and is free of filler. It conveys the core purpose efficiently without wasting words.

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 very simple, zero-parameter read-only tool, this description is largely sufficient. It names the key returned aspects (tier, limits, usage). There is no output schema, so a bit more detail on the structure of these fields could have been helpful, but the low complexity keeps the description reasonably 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?

The tool has zero parameters, and the schema coverage is 100% (trivially, since no parameters exist). The description does not need to elaborate on parameter meanings, and no additional semantics are required. The baseline for zero-parameter tools is 4.

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 verb 'Get' and the specific resource 'subscription status' with the details 'tier, limits, and usage'. This unambiguously distinguishes it from sibling getters like get_project or get_user_info, which target different resources.

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 provides no explicit context on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It simply states what it does, leaving the agent to infer usage from the tool name and sibling 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?

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds behavioral value beyond these by describing what returned entries contain, how 'schema' maps to create_project, and what 'tables' notes indicate about authorization.

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 core purpose and usage guidance, and each major section—template list, schema format principles, and create_project integration—earns its place. It is slightly dense with formatting emphasis, and the closing TIP partially reinforces earlier guidance, but overall it remains 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?

For a zero-parameter, read-only tool with no output schema, the description is complete: it lists available templates, explains the schema format expectations, and tells the agent how the output should be consumed by create_project. No critical decision or next step is left unexplained.

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 input schema has zero parameters, so the baseline is 4 and there is no parameter ambiguity to resolve. The description appropriately focuses on output content and usage rather than parameter details.

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-object statement: 'Get pre-built template schemas for common use cases.' It further distinguishes the tool by positioning it as the first stop when creating a new project and enumerating concrete template names, so an agent can differentiate it from generic schema retrieval tools.

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 provides explicit usage context: 'USE THIS FIRST when creating a new project!' and advises studying templates before creating custom schemas. It does not explicitly state when not to use this tool or compare it to similar siblings, but the guidance is clear and actionable.

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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds the subject of the operation but does not disclose behavioral details such as auth requirements or response format.

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

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

The description is a single, focused sentence with no redundancy or extraneous content. It is front-loaded and efficiently conveys the core purpose.

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 simple with no parameters and good annotations, but without an output schema, the description's reference to 'information' is incomplete. It would be helpful to indicate common fields like username, email, or roles.

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 input schema has zero parameters, so there are no parameter semantics to explain. The description is not required to compensate for any missing schema information, and the baseline for zero-parameter tools is 4.

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 uses the specific verb 'Get' and identifies the resource as 'information about the authenticated user', which distinguishes it from sibling tools like get_project or get_graph_node. However, 'information' is somewhat vague about what exactly is returned.

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?

No guidance is provided about when to use this tool versus alternatives. It does not mention use cases like retrieving the current user's ID or profile, nor does it clarify 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is clear. The description adds meaningful context: it reveals the content (commit SHA, timestamp, message) and the practical purpose (rollback assistance). This goes beyond the annotations without contradicting them.

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 sentences, each earning its place: what it does, what it returns, and when to use it. No fluff, no 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 simple read-only tool with one documented parameter and complete annotations, the description provides sufficient information about the response content and use cases. It also connects to the rollback_project sibling, which is a helpful contextual cue.

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 covers 100% of the single parameter (project_id) with a clear description. The tool description adds nothing about parameters, but this is unnecessary given the schema's completeness. 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: 'Get the deployment and version history (git commits) for a project.' It also specifies the output (schema changes with commit SHA, timestamp, message). It is clear, though it does not explicitly distinguish from the sibling tool get_graph_version_history, which likely serves graph 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?

The description provides explicit use cases: 'Review what changed between deployments, find the last working version before issues started, get commit SHA for rollback_project.' This tells the agent when to use the tool, but it does not mention when not to use it or name alternatives like get_graph_version_history.

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 and idempotentHint=true, and the description reinforces this by stating it only lists pools and never handles credentials. It adds valuable context about the BYOC model, the retirement of owned hosting, and the UI-only registration process, going well beyond 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?

The description is front-loaded with the core purpose in the first sentence, and each subsequent sentence adds essential information: the id’s role, the registration process limitation, and credential handling. It is three sentences with no wasted words.

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?

Despite having no parameters and no output schema, the description completely covers the tool's purpose, return value (cluster id), how to use it with a sibling tool, and its non-behaviors. It provides enough business context (BYOC, retired hosting) for an agent to decide when and how to invoke 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?

With zero parameters, the schema provides complete coverage, and the baseline for 0 params is 4. The description adds contextual meaning about the returned cluster id and its importance for create_project, though it does not need to explain parameters.

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 action ('List') and the resource ('your registered BYOC resource pools'), and specifies that these are client-owned Kubernetes clusters. It also differentiates this tool from siblings by linking the returned cluster id to create_project's cluster_id, making its unique role 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?

It explains when to use the tool: to obtain a cluster id to pass to create_project for deploying on your own infrastructure. It also explicitly states what the tool does not do—registering a pool is a UI action and the tool never handles credentials—providing clear exclusions and 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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral details about pagination (limit/offset) and ordering (newest first), which goes beyond the annotations but does not disclose other potential behaviors such as error conditions or return format. This is acceptable given the annotations but not exceptionally 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?

The description is two sentences, front-loaded with the core purpose and followed by key usage details (pagination, ordering). Every sentence earns its place with no redundancy or 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?

The description covers the essential aspects: entity type scoping, pagination, and ordering. It does not mention the environment parameter, but that is fully documented in the schema. Lack of an output schema means the description could briefly note the return format, but for a list operation this is not a critical gap. The description is sufficiently complete for a read-only listing tool with strong annotations.

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 all five parameters documented. The description mentions limit/offset in the context of pagination, which reinforces the schema but does not add meaning beyond it. Since the schema fully handles parameter semantics, 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 clearly states the tool lists nodes of a specific entity type from a deployed graph project, using the specific verb 'list' and identifying the resource (nodes) and scope (entity type). This distinguishes it from siblings like get_graph_node (single node) and search_graph_nodes (search), making its purpose unambiguous.

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

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

The description implies usage for listing nodes by entity type and mentions pagination, but does not explicitly address when to use this tool versus alternatives like search_graph_nodes or get_graph_node. There is no when-not or alternative guidance, so usage context is only implied, not 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context beyond that: env_var_names returns names and 'never their values', replicas is 0 when frozen and null when the pool is not reporting, and image is tied to the last successful build.

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 intent is front-loaded in the first clause, and every subsequent field note earns its place since there is no output schema. It is dense as a single run-on sentence, which slightly hurts readability but not content efficiency.

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 full return-value burden and does so comprehensively, enumerating every field, its type domain (frontblok/logicblok, staging_status values), and edge-case semantics. Nothing an agent needs to interpret the response 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?

There is a single parameter with 100% schema description coverage, so the schema already documents project_id fully. The description adds no further meaning about that parameter (its mention of module_id is a return field, not an input), making baseline 3 correct.

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 a project's modules and what each runs'), which is enough to separate it from list_projects, list_project_files, and list_project_jobs. It does not, however, explicitly name a sibling it is not, so it stops short of the 5 bar.

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 contains no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_project_info or list_project_jobs. It purely documents the payload; an agent gets no routing help.

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 and idempotentHint=true, and the description adds meaningful behavior beyond that: 'files are not streamed through MCP' and the response contains metadata plus public URLs, not file contents. This prevents an agent from expecting binary data streams.

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 with no filler. The core action and scope are front-loaded, followed by a single high-value behavioral note about file streaming.

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

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

For a simple read-only list tool with annotations covering safety and schema covering parameters, the description supplies the essential missing context: return type (metadata + public URLs), ordering, and the non-streaming behavior. No critical information needed to invoke the tool correctly is absent.

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 input schema already fully documents all four parameters. The description adds useful output-ordering context but no parameter-specific semantics beyond what the schema provides, so the baseline score of 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 the specific action ('List'), the resource ('a project's uploaded files'), and the output scope ('metadata + public URLs'). It also specifies ordering ('most recent first'), which distinguishes it from sibling list tools like list_projects and list_graph_nodes.

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 makes clear this tool is for uploaded project files and positions it as an inspection operation. It does not explicitly name alternative tools or exclusion criteria, but the resource scope is specific enough that an agent can infer when to use it over sibling listing 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds value by disclosing that job records are kept for the life of the project, that results are newest-first, and that pagination semantics indicate the last page. It does not explicitly state rate limits or auth requirements, but the safety profile is already covered by 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?

The description is a single focused paragraph that front-loads the main behavior (list, newest first) and then adds enumeration of contents and pagination instructions. The phrase 'the first job of the job_type you want is the latest' is slightly awkward but informative. Every sentence contributes to usage clarity.

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 listing tool with full schema coverage and annotations declaring safety, the description covers the key use case (finding past operations without job_id) and pagination behavior. No output schema exists, so return format is not explicitly described, but the list of fields (status, error, failure_side, start/end times) gives agents a good expectation of output content.

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 fully documents all three parameters (project_id, limit, offset). The description adds context that offset skips jobs 'newest first' and clarifies pagination, but does not add format or type information beyond the schema. Baseline 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?

Description uses a specific verb and resource ('List a project's jobs'), enumerates the operation types included (create, deploy, promotion, rollback, resource change, module operation), and clarifies it's newest-first. It differentiates from siblings like get_job_status (which retrieves a single job by job_id) by explicitly addressing the case where job_id is unavailable.

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 states when to use this tool: to find what an operation did when job_id is no longer available, e.g., after an interruption or in a later session. It explains pagination behavior ('Read older jobs a page at a time with offset; a page shorter than limit is the last'). It does not name alternative tools, but the use case of locating past jobs without job_id 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the detail that the list includes status and URLs, which is useful but not a deeper behavioral trait. It does not contradict the annotations, so a 3 is appropriate.

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

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

The description is a single, front-loaded sentence that directly conveys the tool's purpose. There is no fluff or repetition of the title, making it very concise.

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?

This is a simple list tool with no parameters, no output schema, and strong read-only annotations. The description adequately indicates what the tool returns (all projects with status and URLs). Despite lacking pagination or output format details, the simplicity of the tool and good annotation coverage make it sufficiently 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?

The input schema is empty with zero parameters, making schema coverage trivially 100%. Per the baseline rule for zero-parameter tools, a score of 4 is warranted. The description does not need to explain parameters since there are none.

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 'List all your RationalBloks projects with their status and URLs', using the specific verb 'list' and identifying the resource (projects). It distinguishes from siblings like 'get_project' and 'get_project_info' by emphasizing 'all' and the listing nature.

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 implies the tool is for listing all projects, which is a clear context. It does not explicitly exclude alternatives such as 'get_project' for a single project, but the word 'all' and the resource scope provide sufficient guidance. No explicit when-not-to-use or alternative names are given, so it scores a 4 rather than 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?

Annotations declare readOnly=false, destructive=false, idempotent=false but disclose nothing about semantics. The description adds the real behavioral payload: it writes to the saved schema but does not deploy, is all-or-nothing (a single bad op refuses the whole patch naming the operation), preserves untouched tables/fields including identity so renames and data survive, and supports optimistic concurrency via expected_version returning 409.

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 with the single most important constraint (patch, don't drop; save, don't deploy), then organized under OPERATIONS / ALL OR NOTHING / EVERY ANSWER IS A DIFF / WORKFLOW headers with copy-pasteable op examples. Length is proportionate to the op grammar an agent must construct, and no sentence is 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 burden and does so by enumerating the response keys ('applied', 'diff', 'summary', 'plan', 'version'). The workflow and atomicity/refusal rules make it callable without guesswork. Minor gap: the diff/plan shapes are named but not illustrated, though that is a small omission for a tool this complex.

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% (baseline 3), but the operations param is typed as an untyped object array whose schema description literally says 'See the tool description for every op and its fields' — so the full op grammar (add_table, rename_table, add_field, rename_field, set_field, set_table) with concrete JSON examples exists only here. The description also explains expected_version's race-refusal semantics and that set_field merges/null-deletes.

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 precise verb+resource+scope: 'Change PART of a project's schema without dropping any of it (saves to database, does NOT deploy).' It explicitly carves itself away from siblings update_schema and drop_schema_items, including naming the sibling that handles drops.

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?

Provides an explicit 4-step workflow (get_schema → preview_schema_change → patch_schema → deploy_staging/get_job_status) and an explicit exclusion ('Dropping a table or field is drop_schema_items, a tool of its own'). It also states the condition that triggers a refusal (expected_version / 409), which tells the agent when to pass it.

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), but the description adds substantial context beyond them: the exact response keys, that invalid relational schemas are refused here with the reason, and that 'version' is a concurrency token for the following save. That is real behavioral disclosure an agent needs for the next call.

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 the core verb and constraint, then cleanly bulleted. The ANSWER paragraph is long but justified given there is no output schema, though the opening clause mildly restates the tool 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?

With no output schema, the description carries the return contract (applied, diff, summary, plan, version) and the failure mode, all of which an agent needs to act on the result. Nothing material is missing for a 3-param preview 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 baseline is 3, but the description adds meaning the schema does not: which project types each of schema/operations applies to and that operations is exactly the payload patch_schema or drop_schema_items would take. project_id semantics are left to the schema, which is fine for a UUID.

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 (preview a schema change) and immediately contrasts it with the siblings it mirrors: patch_schema and drop_schema_items, which actually save. The phrase 'saving nothing ... before it is saved' makes the preview-only nature unmistakable against the mutate siblings.

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 caller: pass ONE of operations (relational projects) or schema (relational or graph), and states it is 'the one way to see what a change would do before it is saved'. It also tells the agent to feed the returned version into the subsequent save as expected_version, giving forward guidance no sibling provides.

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 annotations only covering the safety profile (non-readonly, non-idempotent, non-destructive), the description adds substantial behavior: data and settings untouched, project API (staging/production) and backend modules restart to pick up the CORS origin, asynchronous execution, one-operation-per-module/scope locking, the exact refusal messages, and retry timing.

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?

Dense but front-loaded: the core rebuild/roll-out action and non-destructive data note lead, then async polling, then the concurrency and update-refusal edge cases. Every sentence carries operational meaning, though the closing paragraphs are wall-of-text heavy.

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 compensates by explaining that a job_id is returned, that get_job_status names the built image/commit, and how completion surfaces in list_modules. Combined with the concurrency and retry guidance, nothing essential for correct invocation 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% and there is only one parameter (module_id), which the schema already documents and the description reinforces by pointing to list_modules. Baseline 3 is appropriate since the description adds no syntax or format detail 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 precise verb and resource: rebuild a module from its repository's default branch head and roll it out while keeping pod count. This distinguishes it from siblings such as deploy_module, update_module, and redeploy_project, and an agent can identify the operation 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 clear operational context: poll the returned job_id via get_job_status and confirm with list_modules, and it explains the concurrency refusal case and the RationalBloks-update retry. It does not explicitly say when to choose this over deploy_module or redeploy_project, so it stops short of full alternative 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 cover the safety profile, but the description adds substantial context they don't: 409 refusal conditions, the rule that a concurrent in-flight save is refused rather than deployed, single-operation-at-a-time locking with the running job named in the refusal, and platform-update refusals. This is exactly the extra behavioral detail the annotations can't provide.

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 scope, then structured around refusal conditions and async behavior. It is dense and slightly run-on, but nearly every clause carries operational information an agent needs; little is redundant with 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?

For an asynchronous mutation with no output schema, the description supplies the missing pieces: the returned job_id, polling via get_job_status, and concurrency/retry guidance. Nothing an agent needs to invoke and follow up on this call is absent.

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% with a single parameter, so the schema already carries the full semantics; the description's 'relational or graph project' note duplicates the schema's own parenthetical. Baseline 3 is appropriate 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?

Starts with a specific verb+resource+scope: 'Rebuild and roll out a project's staging environment from the schema it runs, with NO schema change.' It explicitly distinguishes itself from deploy_staging (which applies unapplied schema changes) and deploy_production (which targets production), so an agent can route correctly without opening a 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?

Names the alternatives and the exact conditions that select them: deploy_staging 'deploys those' when saved schema holds unapplied changes, and deploy_production handles production when staging matches production. It also gives concrete when-not conditions (409 refusals) and instructions for retry.

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 the operation is a write (readOnly=false), idempotent, and non-destructive. The description adds useful context beyond annotations by clarifying exactly what attribute changes ('display name') and what does not ('project_code'), preventing any misunderstanding about the tool's effect. It does not contradict 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?

The description is a single, concise sentence with a parenthetical that adds essential scope information. It is front-loaded with the primary action, contains no redundant words, and every part contributes to understanding the tool's 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?

This is a simple mutation tool with only two parameters and no output schema. The description clearly states what the tool does and what it does not affect. While it could mention immediate persistence or side effects, those are not typically necessary for a straightforward rename, and the annotations cover safety characteristics. The description is sufficiently complete for its complexity.

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% for both parameters, so the schema already explains that 'name' is a new display name and 'project_id' is a UUID. The description does not add any additional parameter-level meaning beyond what is already present in the schema, so a baseline score 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 uses a specific verb+resource ('Rename a project') and adds a crucial scope distinction ('changes display name, not project_code'). This clearly differentiates the tool from any potential update or modification tools and accurately states its exact function.

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 implicitly communicates when to use the tool: whenever a project's display name needs to be changed. The parenthetical exclusion of project_code provides a clear boundary, but it does not explicitly name alternative tools or state 'use this instead of X'. Context is clear, though no direct comparison exists.

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 destructiveHint=true and idempotentHint=false, but the description adds material behavior well beyond them: the exact scope of destruction (schema + code, not Neo4j data), the post-rollback API redeployment, single-operation-per-project locking with a named blocking job, and the transient RationalBloks refusal. These are the details an agent needs before firing an irreversible call.

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, the warning follows immediately, then recovery instructions. Almost every sentence carries operational weight; the final RationalBloks sentence is somewhat verbose but still actionable, and nothing is redundant with the annotations.

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, irreversible-looking mutation with no output schema, the description covers scope, side effects, and error/retry handling thoroughly. Remaining gaps are minor: no mention of what the call returns or how the environment parameter interacts with the rollback.

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 description's only param-adjacent information ('commit SHA of the version you want to rollback to', discoverable via get_graph_version_history) restates the schema. It says nothing about the environment parameter's effect on a rollback, so it does not exceed the 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 gives a specific verb and resource ('Rollback a graph project to a previous version') and immediately scopes it with what is and is not reverted (schema AND code yes, Neo4j data no). It does not explicitly distinguish itself from the sibling rollback_project, so an agent must infer the graph vs. non-graph split from the name alone.

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 how to prepare ('Use get_graph_version_history to find the commit SHA') and how to recover from the two documented refusal conditions (wait via get_job_status and retry; retry in a few minutes during RationalBloks updates). There is no explicit 'do not use this when...' alternative, but the operational routing guidance is unusually strong.

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 destructiveHint annotation, the description discloses precisely what is reverted (schema and code) and what is not (database data), plus operational behavior: one project operation at a time, refusal messages naming the running job, and temporary refusal during RationalBloks updates. This is rich behavioral context that materially improves safe invocation.

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 core action and a prominent warning, then proceeds through prerequisites, post-rollback monitoring, use case, concurrency, and service-update behavior. Every sentence conveys operationally relevant information with 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 destructive, non-idempotent mutation with no output schema, the description supplies the prerequisite tool, the post-action monitoring tool, side-effect boundaries, and concurrency/error behavior. An agent has enough to decide when and how to call it 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 description coverage is 100%, so all three parameters are already documented. The description reinforces the version parameter as a commit SHA but adds no syntax, constraints, or environment semantics beyond the schema, matching the baseline for full 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 description clearly states a specific verb and resource: 'Rollback a project to a previous version,' and specifies the scope as schema AND code while excluding database data. It does not explicitly differentiate this tool from the sibling rollback_graph_project, 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?

It gives clear workflow guidance: use get_version_history to find the target SHA, then get_job_status to monitor redeployment, and states the primary use case of recovering from schema changes that break deployment. It lacks explicit when-not-to-use guidance or direct comparison to the sibling rollback_graph_project.

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

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

Annotations only declare readOnly=false, idempotent=true, destructive=false. The description adds substantial behavioral detail beyond them: concurrency locking semantics, the exact refusal signal, the coordinating tool (get_job_status), and update-window retry behavior. This is exactly the operational context an agent needs and 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?

Front-loaded with the core operation, then layered with constraints - every sentence carries actionable content (sibling contrast, concurrency rule, retry path, maintenance retry). It is dense with colons and semicolons, which slightly hurts readability, 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?

For a mutation tool with no output schema and full schema coverage, the description is complete: it covers what the operation does, its concurrency model, refusal handling, coordination with get_job_status, and maintenance-window retries. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents module_id (with list_modules pointer) and the replicas enum. The description's '1 or 2 pods' merely restates the enum range, adding no syntax or format detail beyond the schema. Baseline 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?

States a specific verb+resource ('Run 1 or 2 pods of a module') and immediately names the sibling it contrasts with (freeze_module stops it). An agent can distinguish this from freeze_module, unfreeze_module, and set_module_resources 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?

Gives explicit when-to-use context: one operation per module and per project at a time, what happens on refusal (the refusal names the running job), and the prescribed recovery (wait via get_job_status, then retry). It also covers the maintenance-window case with the exact refusal string and retry delay.

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, and non-destructive behavior, so the description does not need to repeat safety. It adds valuable behavioral details: contains search via '~' prefix, case-insensitivity, and all-node-type search when entity_type is omitted.

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?

Description is compact and well-organized: one-line summary, a bullet for supported modes, and three concise examples. Every sentence earns its place, and the most important information appears early.

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 tool's simple read-only nature and complete schema documentation, the description covers the key usage semantics. It does not describe the return shape, but no output schema is provided and the search behavior is the main concern; a short note on response format would elevate completeness, but the current state is adequate.

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%, yet the description adds meaningful interpretation beyond schema: examples for exact/contains filters, combined filter behavior, and the semantic of omitting entity_type. This is more than enough for an agent to construct valid queries.

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?

Description states the specific action ('Search for nodes by property values') and resource ('deployed graph project'). It clearly distinguishes from sibling tools like get_graph_node, list_graph_nodes, and fulltext_search_graph by emphasizing property-based search with exact/contains modes.

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?

Description provides concrete usage examples, including exact match, contains search, and combined filters, and explicitly explains behavior when entity_type is omitted. It does not explicitly name alternative tools or when not to use this tool, but the context is clear enough for most cases.

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?

Goes far beyond the annotations (destructiveHint=true etc.) by disclosing that values are encrypted and never returned, that the answer/list_modules only name variables, that backend modules restart while frontend modules rebuild, that platform variables are reserved, and that the operation is job-based with a per-module/per-project concurrency lock.

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-loads the core operation and then layers the important edge cases, though it is a dense run-on paragraph that could be split for readability. Every clause carries real information, so little 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?

With no output schema, the description fully covers the async return contract (job_id + get_job_status polling), the destructive/irreversibility caveat, and the failure modes, leaving nothing an agent needs to call it correctly 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 coverage is 100% (both parameters documented), so the baseline is 3, but the description adds value beyond the schema: the set/remove/keep merge rule and the fact that values are encrypted and never returned, which shapes what the agent may expect back.

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 ('Set a module's environment variables') with the exact merge semantics, clearly distinguishing it from siblings like update_module or set_module_resources.

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 concrete operational guidance: poll get_job_status for the returned job_id, wait for the running job before retrying when refused, and retry during the update window. It names relevant siblings (get_job_status, list_modules) but does not explicitly contrast when to choose this over set_module_resources or update_module.

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?

Adds substantial behavior beyond the annotations: allocation is validated against pool capacity before applying and a refused allocation is restored, the call is asynchronous and returns a job_id to poll, there are per-module and per-project mutual-exclusion constraints, and maintenance windows produce a specific retryable refusal. This is exactly the retry/idempotency/auth context an agent needs.

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-loads what the tool does, then follows with async, concurrency, and retry semantics in order of operational importance. It is dense and slightly repetitive around get_job_status usage, but almost every sentence carries distinct 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 3-parameter mutation with no output schema and full schema coverage, the description covers the async flow, refusals, and concurrency rules an agent must handle. It could still note whether resources can be lowered or what the job result reports, but nothing essential for invoking it correctly is missing.

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

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

Schema description coverage is 100%, so module_id, cpu_millicores, and memory_mb are already documented in the schema. The description adds the capacity-check constraint on the allocation but no format, range, or unit nuance beyond what the schema provides, so the baseline of 3 applies.

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

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

States a concrete verb (set) and resource (module's CPU and memory) plus the side effect (rebuild so pods take them), which is a specific operation an agent can recognize. It does not explicitly contrast itself with the near-siblings scale_module, update_module, or redeploy_module, so sibling differentiation is left to 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?

Gives explicit operational context: results are asynchronous and must be polled via get_job_status, only one operation per module/project at a time, and how to recover from a refusal (wait for the named running job, then retry) or a maintenance-window refusal. It never states when to prefer this tool over scale_module/update_module, so the alternative-selection guidance is missing.

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 destructiveHint=false, so safety is covered. The description adds behavioral context beyond annotations by explaining that results include distance from the start, and that traversal is constrained by max_depth and direction. It also mentions filtering by relationship types. It does not discuss cycles or performance, but the added context is meaningful.

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 concise and well-structured: a clear opening sentence, a succinct output summary, a usage statement, a concrete example, and a closing note on filtering. Every sentence contributes necessary information without fluff or redundancy. The example is included as a code block, improving readability.

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 tool with 8 parameters, no output schema, and graph traversal complexity, the description provides a solid overview. It explains the return value ('nodes reachable within max_depth hops, with their distance'), the example with parameters, and support for filtering. It does not detail the exact response structure (e.g., JSON fields), but the description is sufficient for an agent to understand when and how to invoke the tool. Slight gap in not mentioning default behavior (direction=both, max_depth=3) which is only in the schema.

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 baseline is 3. The description adds semantic value through a concrete example ('Start from "Alan Turing", traverse outgoing relationships up to 3 hops deep') and explains that relationship_types is a filter in UPPER_SNAKE_CASE. It clarifies how direction and max_depth work in context, enriching the bare schema descriptions.

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 tool's purpose: 'Walk the graph from a starting node, discovering connected knowledge' and specifies the output: 'Returns all nodes reachable within max_depth hops, with their distance from the start.' This distinguishes it from siblings like get_node_relationships, which likely only returns immediate neighbors, and search_graph_nodes, which is search-based.

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 provides clear usage context: 'Essential for exploring knowledge graphs — find related concepts, trace connections, discover clusters.' While it doesn't explicitly name alternative tools or state when not to use it, the context implies it is for multi-hop traversal rather than single-hop lookups. The example also clarifies typical invocation. Missing explicit exclusions, but adequate.

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 mark this as a non-read-only, idempotent, non-destructive mutation, so the bar is lower; the description still adds substantial context beyond them. It discloses the concurrency model (one operation per module, none concurrent with its project's operations), that it restores the pre-freeze pod count, and quotes the refusal messages verbatim along with recovery steps.

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 no-op behavior are front-loaded, then concurrency and retry semantics follow in a logical order. Every sentence carries distinct operational information, though the third sentence is dense enough that it could be tightened slightly.

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 still covers the risky surfaces an agent needs: concurrency conflicts, retry guidance, and error strings. It does not describe the resulting module/pod state after success or expected latency, which is a minor gap for a mutation 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% and the single required parameter module_id is already documented in the schema with a pointer to list_modules. The description implies the target module but adds no syntax, format, or sourcing detail beyond the structured field, 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?

The description uses a specific verb and resource ('Start a frozen module's pods again') and immediately scopes it against the opposite case ('A running module is left as it is'). This clearly contrasts with freeze_module and distinguishes it from a generic restart, so the agent can pick it 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?

It states the precondition (module must be frozen), the no-op case, and the exact failure modes with remediation: wait for the running job via get_job_status then call again, and retry in a few minutes during a RationalBloks update. Explicit when-to-use and when-to-retry guidance is provided, including the named sibling tool to call for recovery.

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=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description reinforces that unspecified fields remain unchanged, which is meaningful mutation semantics, but overlaps with the schema's "partial update" note and says nothing about permissions, error behavior on a missing node, or confirmation of the write.

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 short sentences, front-loaded with the action and resource, and the second sentence delivers the one behavioral rule that matters most for calling it correctly. 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?

For a non-destructive, idempotent mutation whose annotations already cover the safety profile and whose schema fully documents inputs, the description is nearly sufficient. It only leaves open what happens when the target node does not exist, which is a minor gap given there is no output schema to explain returns.

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 every parameter is already documented in the schema, including the partial-update nature of `data` and the environment default. The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ("Update properties of an existing node") and scopes it to a deployed graph project, which cleanly separates it from create_graph_node and delete_graph_node. It does not name a sibling explicitly, but the intent is unambiguous.

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