RationalBloks

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds useful behavioral context: the 500-call limit, the use of Neo4j UNWIND for high performance, and the requirement that entity_id be unique. However, it does not explain failure behavior, partial writes, or return format, so transparency 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 front-loaded with the primary action and limit in the first sentence. The use case and parameter requirements are concise. The example is somewhat long but necessary for showing the nested node structure. No wasteful 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 bulk write tool with no output schema, the description covers the core behavior, limits, example usage, and parameter requirements. It lacks explicit error-handling or idempotency notes, but annotations cover idempotency, and the example provides practical context. Overall, the description is sufficiently complete for safe invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the internal structure of the 'nodes' parameter ('Each node needs: entity_id (unique string) and data (properties dict)') and providing a concrete example with 'entity_type' and 'nodes' array. This helps the agent construct valid input.

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 'Create multiple nodes at once' with a specific resource (graph nodes) and a scope limit ('up to 500 per call'). It distinguishes itself from the singular sibling tool 'create_graph_node' by emphasizing the bulk nature, and the example reinforces the 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?

It explicitly positions the tool for knowledge graph population: 'Essential for knowledge graph population — create hundreds of entities from a single book chapter or article.' This indicates when to use it, though it does not explicitly mention alternatives or when not to use it (e.g., for single-node creation).

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 this is a non-read-only, non-destructive operation. The description adds valuable behavior details: the 500-per-call limit, the Neo4j UNWIND optimization, and the required structure for each relationship. It does not contradict the annotations and provides useful contextual information beyond the structured hints.

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 appropriately sized and structured: a concise first line, a high-level use-case sentence, a clear requirements list, and a concrete example. Each sentence contributes, though the example is somewhat long. 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?

Given the tool's complexity (nested array parameter, batch limit, no output schema), the description is largely complete: it covers batch size, performance rationale, required fields, and provides an example. It could be more complete by mentioning whether the operation is asynchronous or returns a job identifier, but the current coverage is sufficient for correct invocation.

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

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

With 100% schema description coverage, the schema itself is adequate. The description adds semantic value by explicitly stating each relationship needs from_id, to_id, and optional data, and by providing a concrete example with rel_type and relationships. This clarifies the expected format beyond the schema's generic 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 function: 'Create multiple relationships at once' and describes linking hundreds of concepts, people, and events. It distinguishes itself from bulk_create_graph_nodes (different resource) and create_graph_relationship (single relationship) by explicitly mentioning the batch/performance aspect.

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 a clear use case: connecting many knowledge items in one operation, with a batch limit of 500 and performance benefits via UNWIND. It implies this is the tool for bulk creation, but it does not explicitly name alternatives or state when not to use it, leaving some room for improvement.

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 mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds useful constraints: entity_type must match schema, and entity_id should be a meaningful unique identifier. It could further clarify the effect of the environment parameter or response behavior, but it does not contradict 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 compact and well-structured: a one-sentence summary, a required-prerequisite note, schema guidance, and an example. Every sentence earns its place, and the example is illustrative without being verbose.

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 prerequisites, schema matching, and unique ID guidance. However, it omits information about return values, error cases, or the environment parameter's default behavior, which would be useful given there is no output schema. 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?

With 100% schema description coverage, the baseline is 3. The description adds value beyond the schema by explaining that entity_id is a unique identifier and providing a concrete example that illustrates how data should be structured for an entity type like 'person'. This clarifies the nested object usage.

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 ('Create') and resource ('single node in a deployed graph project'), clearly distinguishing it from sibling tools like bulk_create_graph_nodes and create_graph_relationship. It also states the key parameters (entity_type, entity_id, data) upfront.

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 a required prerequisite: the project must be deployed, and directs users to deploy_graph_staging first. It also instructs users to consult get_graph_data_schema for valid entity types, providing clear when-to-use and preparation 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 mark this as readOnly=false and destructive=false. The description adds valuable behavioral context beyond those annotations: deployment takes 2-5 minutes, the call can be refused transiently, a cluster_id is required because owned hosting is retired, and the result should be monitored via get_job_status. No contradiction with annotations exists.

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 long but well-structured with a warning header, schema example, field types, cardinality options, hierarchical example, numbered rules, and workflow. It is front-loaded with the purpose. Minor redundancy exists because 'Use get_graph_template_schemas FIRST' appears in both Rule 8 and Workflow step 1, but the length is justified by the complexity of the schema format.

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 is highly complete for a complex creation tool: it documents the required schema shape, field types, relationship cardinalities, naming conventions, required and optional keys, automatic fields, deployment behavior, and monitoring workflow. Even without an output schema, it tells the caller that a job_id is returned for status tracking.

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 substantial meaning beyond the schema by documenting the exact graph schema structure: nodes, relationships, field types, cardinality, hierarchical inheritance, and validation rules. It does not add much for name or cluster_id, but those are already well documented in the input schema.

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

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

The description opens with 'Create a new Neo4j graph database project from a hierarchical JSON schema', a specific verb, resource, and input format. This clearly distinguishes it from generic create_project and from node/relationship-level graph tools such as create_graph_node and create_graph_relationship.

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 workflow: first use get_graph_template_schemas, then call this tool, then monitor with get_job_status. It also states when to retry during the 'RationalBloks is being updated' refusal. It does not explicitly list when-not-to-use conditions or name alternative creation tools, but the context and workflow are clear enough.

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 mutability and non-idempotence. The description adds context by stating that rel_type must match a schema key and that from_id/to_id must be entity_ids of existing nodes, which are important validation constraints not visible in the schema alone. It also implies a deployed graph project is required. 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 concise and well-structured: a purpose statement, two validation rules, a concrete example, and a requirement note. Every sentence adds value, and the example is placed near the top for quick comprehension.

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 annotations, the description covers preconditions (valid rel_type, existing nodes), shows a full example, and defines the data shape. It does not describe return values or async behavior, but no output schema is present and the provided context is strong enough for an agent to invoke correctly. Slightly incomplete regarding what happens on success.

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 a baseline of 3 applies. The description enriches key parameters: it explains rel_type must match a schema key with an example, and clarifies that from_id and to_id must be existing node entity_ids. The data parameter is also illustrated with an example. Project_id and environment are left to the schema, which is sufficient given the high base 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 function: 'Create a relationship between two nodes in a deployed graph project.' It uses a specific verb (create) and resource (relationship between nodes), and the example with rel_type 'authored' and node IDs distinguishes it from sibling tools like create_graph_node and bulk_create_graph_relationships.

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 instructs users to 'Use get_graph_data_schema to see available relationship types,' which is a clear prerequisite and alternative guidance. However, it does not explicitly contrast with the bulk version or other alternatives, so it lacks full exclusion 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?

The description discloses that creation is asynchronous via a returned job_id, that deployment takes 2-5 minutes, and that calls may be refused with a specific message while updates occur. It also documents strict schema validation requirements. These behavioral details go well beyond the annotations, which only state readOnly=false, openWorld=true, idempotent=false, and destructive=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?

The description is long but exceptionally well structured with headings, numbered rules, examples, and a workflow. It is front-loaded with the purpose and then organized by critical constraints. Some repetition exists across examples, but each block serves a distinct instructional function, making the length justified.

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 properly supplies the return/job monitoring path and expected deployment duration. It also covers prerequisites, cluster_id requirements, backend selection, schema validation rules, and retry behavior. An agent has enough context to invoke the tool correctly and recover from failures.

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

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

Although the input schema covers all 4 parameters (100% coverage), the description adds substantial meaning: flat-format rules, per-type requirements like max_length and precision/scale, automatic fields to omit, authentication/authorization guidance, array type semantics with GIN indexing, and backend engine tradeoffs. This is exactly the practical knowledge an agent needs 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 opens with a precise verb and resource: 'Create a new RationalBloks project from a JSON schema.' This clearly identifies the tool's core function and distinguishes it from graph/schema siblings like create_graph_project. The extensive schema rules reinforce the exact purpose without ambiguity.

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 section gives explicit sequencing: use get_template_schemas first, then call this tool, then monitor with get_job_status. It also states retry behavior when RationalBloks is updating. However, it does not explicitly exclude alternatives such as 'use create_graph_project for graph projects,' 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?

The description explicitly discloses the destructive cascading behavior: 'This also removes all relationships connected to this node (DETACH DELETE)'. This goes beyond the annotated destructiveHint=true by specifying the exact scope of destruction, which is valuable context for an agent. No contradiction with annotations is present.

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 exceptionally concise: two sentences that front-load the purpose and then emphasize the key warning. Every word contributes meaning, with the warning emoji drawing attention to the side effect. No wasted content.

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 delete operation, the description covers the essential context: what is deleted, the cascading effect, and the target environment ('deployed graph project'). The schema handles parameter details, and no output schema is expected for a delete operation. It could mention irreversibility explicitly, but the destructiveHint annotation and 'DETACH DELETE' warning make the behavior clear enough.

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% description coverage for all four parameters, so the description does not need to explain them. The tool description itself does not add extra parameter semantics beyond what the schema already provides, which is acceptable 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 action ('Delete a node and all its relationships') and the target resource ('from a deployed graph project'). It distinguishes itself from sibling tools like delete_graph_relationship by specifying it removes the node and all connected relationships, making its scope 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 conveys when to use the tool: when you need to delete a node and its relationships from a deployed graph. It does not explicitly mention alternatives (e.g., delete_graph_relationship for removing only a relationship), but the context of 'deployed graph project' and the explicit cascading behavior provide sufficient situational 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 declare destructiveHint=true and readOnlyHint=false, and the description reinforces and extends this by listing exactly what is destroyed (GitHub repo, K8s deployments, Neo4j DB, credentials). It also discloses async job behavior, concurrency constraints, and refusal conditions—none of which are in the annotations, adding significant transparency.

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

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

Three sentences, each earning its place: the first states the action and scope, the second covers job polling and concurrency, the third covers the specific RationalBloks refusal. Information is front-loaded with the destructive effect stated first, and there is 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?

For a destructive async operation with no output schema, the description covers everything an agent needs: what is deleted, how to track completion (poll job_id), how to handle concurrency refusals, and when to retry. Sibling tool existence is noted but the description makes this tool's behavior self-contained.

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 single parameter project_id is fully described in the schema as 'Project ID (UUID)', which is clear and sufficient. The description adds no additional parameter-level information, but with 100% schema coverage, the schema already carries the meaning. 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 states a specific verb (delete) and resource (graph project) and enumerates what gets removed (GitHub repo, K8s deployments, Neo4j database, credentials). This clearly distinguishes it from siblings like delete_graph_node and delete_graph_relationship, 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?

Provides explicit operational guidance: tells the agent to poll the returned job_id with get_job_status, explains that only one operation runs per project at a time and how to handle refusals, and gives the exact error message for the RationalBloks update condition. This is concrete and actionable, going beyond vague 'use when' advice.

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 readOnlyHint=false, so the destructive nature is known. The description adds the identification mechanism (internal ID) and the prerequisite call, but doesn't disclose irreversibility or cascading effects beyond 'delete.' This adds context but not deep behavioral detail.

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 deliver the purpose and a key prerequisite with no waste. The most critical information is front-loaded, making it efficient and well-structured.

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 4 parameters (3 required), no output schema, and a terse description. While annotations cover safety and schema covers parameters, the description omits outcomes (e.g., success/failure behavior, permanence, async semantics). For a destructive operation, more context would be valuable, but the given essentials are 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% with each parameter having a description, so the baseline is 3. The description reinforces rel_id's provenance by mentioning 'internal ID' and references get_node_relationships, which mirrors the schema description but doesn't add new format or constraint 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 uses the specific verb 'Delete' and identifies the resource as 'a specific relationship by its internal ID.' It clearly distinguishes from siblings like delete_graph_node and create_graph_relationship by naming the exact object and deletion method.

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

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

It provides clear context by stating this deletes a specific relationship by ID and instructs to use get_node_relationships to find the ID. While it doesn't list explicit 'when not to use' exclusions, the directive to reference a sibling tool for ID lookup indicates a clear usage path.

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 destructive and non-idempotent behavior, but the description adds crucial details: it runs as a job, requires polling, enforces single-operation-per-project, and may be refused during external updates. These behaviors are not in annotations, so the description adds significant value.

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 convey all necessary information without excessive verbosity. The main action and scope are front-loaded, followed by polling and refusal handling. Slightly dense but well-structured for a complex destructive operation.

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 async tool with no output schema, the description covers all required operational details: polling mechanism, conflict handling, and retry logic. An agent has everything needed to invoke and manage the job 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 description coverage is 100%, with project_id described as 'Project ID (UUID)'. The description does not add anything beyond this, so it meets the baseline but does not exceed it.

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

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

The description states a clear verb ('Delete') and resource ('project'), and enumerates exactly what deletion entails (GitHub repo, K8s deployments, database). This distinguishes it from related tools like delete_graph_project. The purpose is 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?

Explicitly instructs the user to poll the returned job_id with get_job_status, and explains refusal conditions (concurrent operation or RationalBloks update) with next steps. This provides complete usage guidance for a complex asynchronous operation.

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

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

Beyond the annotations, the description discloses important behavior: deployment creates a separate production instance, requires a paid plan, destructive drops are refused until confirm_destructive=true, only one operation runs per project at a time, and transient 'RationalBloks is being updated' refusals should be retried. This is rich, actionable behavioral context and 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 front-loaded with its core purpose, then provides tightly packed, non-redundant operational caveats. Every sentence earns its place: prerequisites, destructive confirmation, concurrency, and transient retry conditions are all material to calling the tool correctly.

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 output schema, the description covers the prerequisite (paid plan), the destructive guard, the one-job-at-a-time rule, and the retry path via get_job_status. An agent has enough information to know when to call it, what may cause refusal, and how to recover.

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 both project_id and confirm_destructive. The description reinforces the destructive-confirmation semantics ('pass confirm_destructive=true after reviewing the plan') but adds little beyond the schema's own parameter descriptions. 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: 'Promote graph staging to production' and adds that it 'Creates a separate production Neo4j instance with its own credentials and database.' This clearly distinguishes it from deploy_graph_staging by direction and from generic deploy_production/deploy_staging by being graph-specific.

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 when to use the tool: when promoting a graph staging environment to production and when the paid plan is available. It also gives practical operational guidance about retrying after a concurrent job finishes or after the RationalBloks update message. It does not explicitly enumerate alternatives or say 'use deploy_graph_staging instead,' 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=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds substantial behavioral context beyond annotations: the operation is asynchronous and returns a job_id, it takes 2-5 minutes, it can be refused due to concurrency or RationalBloks updates, and destructive deploys require confirm_destructive=true. It does not contradict annotations. A small gap: it doesn't explicitly state that the operation mutates the staging environment, but the pipeline steps and destructive hint make that clear.

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

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

The description is dense but well-structured: it front-loads the purpose, then lists the pipeline steps, then covers async behavior, monitoring, verification, destructive confirmation, and concurrency/refusal conditions. Every sentence adds value, though the length is justified by the complexity of the operation. It could be slightly tighter, but the structure is logical and scannable.

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 complex, asynchronous, destructive deployment tool with no output schema, the description covers everything an agent needs: what happens, how long it takes, how to monitor, how to verify, when confirmation is required, and what to do on refusal. The only minor omission is the exact shape of the job_id response, but the description explicitly says to use get_job_status, which is sufficient.

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 both parameters. The description adds meaning to confirm_destructive by explaining when it is required (a deploy that drops data is refused without it) and that it should be set only after reviewing the plan. This is useful but not extensive; the baseline of 3 is appropriate because the schema carries 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?

The description states a specific verb ('Deploy') and resource ('graph project to the staging environment'), and enumerates the exact pipeline steps (schema validation, code generation, Docker build, GitHub commit, Kubernetes deployment). It clearly distinguishes this from siblings like deploy_graph_production and deploy_staging by naming the staging environment and the graph-specific pipeline.

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 tells the agent when to use this tool (deploy a graph project to staging), how to monitor it (get_job_status), how to verify success (get_graph_project_info), and what to do when refused due to concurrent operations or RationalBloks being updated. It also names the destructive-confirmation requirement, which is a critical usage condition.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds valuable behavioral context: the paid-plan requirement, the refusal behavior for concurrent operations, the naming of the running job, the wait-and-retry guidance, and the specific 'RationalBloks is being updated' refusal message. This goes 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 compact and front-loaded with the core action and requirement ('Promote staging to production (requires paid plan)'), followed by refusal conditions. Every sentence adds behavioral information. It could be slightly more structured, but it is efficient and free of 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 mutation tool with no output schema, the description covers the key operational constraints: paid plan, destructive confirmation, concurrency refusal, and retry guidance. It doesn't describe the success response or what the deploy plan looks like, but the schema and annotations cover the parameters and safety profile. The main gap is not describing what a successful call returns, which is minor given the tool's 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%, so the schema already documents both parameters. The description adds meaning to confirm_destructive by explaining that a deploy dropping tables/columns/entities/relationships/fields is refused without it, and that it should be set only after reviewing the plan. This is useful but not extensive; the baseline 3 applies because the schema carries 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?

The description states a specific verb and resource ('Promote staging to production') and distinguishes it from deploy_staging and deploy_graph_production by naming the promotion direction. It doesn't explicitly name the sibling it is not, but the promotion semantics are clear enough to separate it from staging deploys.

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 clear context for when to call it (promote staging to production) and when the call will be refused (while another operation runs, while RationalBloks is being updated, or when a destructive deploy lacks confirmation). It doesn't explicitly say 'use deploy_staging instead for staging-only changes,' but the promotion wording implies the alternative.

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 destructiveHint=true and idempotentHint=false; the description goes further by disclosing the asynchronous nature (returns immediately with a job_id), the typical 2–5 minute duration, the refusal for destructive changes unless confirm_destructive=true, and the concurrency lock. It also explains the error-start clue for platform vs schema errors, which annotations do not provide. There is no contradiction with 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 fairly long but front-loaded and highly informative. Every sentence earns its place—the numbered pipeline steps improve scannability, and the troubleshooting guide is directly actionable. It loses one point for being dense: the troubleshooting section could be tightened, and the numbered list plus the parentheses-heavy error guidance make it slightly harder to parse quickly.

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

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

Given a mutation tool with destructive potential, no output schema, and two parameters, the description covers what an agent needs to call it correctly: input (project_id, confirm_destructive), asynchronous behavior (job_id), monitoring (get_job_status), success verification (get_project_info), failure diagnosis (error prefix), and concurrency/update refusals. It is comprehensive enough that an agent can invoke it safely without additional 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 schema already documents both parameters well. The description nevertheless adds value by explaining the semantics of confirm_destructive (a deploy that drops data is refused until you pass true after reviewing the plan), and by mentioning project_id implicitly in the context of 'a project at a time' and the deployment pipeline. Minor deduction: it does not explicitly restate project_id as a UUID, but the schema already does that.

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 specific verb+resource ('Deploy a project to the staging environment'), and enumerates the exact deployment pipeline steps (schema validation, Docker build, GitHub commit, Kubernetes deployment, DB migrations). It further distinguishes itself from siblings by being asynchronous and returning a job_id, versus the production deployment tools which target a different environment.

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 tells the agent when to use the tool and what to do while it runs: use get_job_status with the returned job_id to monitor progress; use get_project_info to confirm success. It also covers when NOT to call it—if another operation is running on the same project, or during the 'RationalBloks is being updated' window—and how to recover by waiting and retrying.

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 already mark the tool read-only and idempotent, and the description adds rich, non-obvious behavior: terminal states, guaranteed eventual completion, timeout estimates, and failure-side semantics. This significantly exceeds what the annotations and schema 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?

Although longer than typical descriptions, every sentence is information-dense and earns its place. The description is front-loaded with the core purpose, then flows naturally through status values, polling guidance, and failure handling without repetition 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?

With no output schema, the description compensates by explaining the status vocabularyable, terminal behavior, and relevant output fields (failure_side, error). The implementation guidance is sufficiently complete for an agent to poll and react correctly across all branches.

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 single parameter job_id has full schema description coverage ('Job ID returned from deployment operations'), so the schema carries the semantic weight. The tool description adds no further parameter-specific meaning, which is acceptable given 100% 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?

States the specific verb 'Check' and resource 'status of a job', and enumerates the job operations it applies to (create, deploy, promotion, rollback, deletion). This is unambiguous and distinct from the deployment-creation siblings, so an agent knows exactly what this tool observes.

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 explicit polling instructions: call until 'completed' or 'failed', with concrete time expectations for failed servers and deploy duration. It also tells the agent what to do on 'failed' based on failure_side, including the key exclusion that 'platform' failures should be reported rather than fixed via schema changes.

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?

The description goes beyond annotations by detailing the response structure (FLAT format mapping), and clarifies the semantic of 'saved_schema_deployed' field with conditions (true when last deploy applied it, false when saved after last deploy, null when no deployed schema). This adds significant behavioral context about the response state that annotations do not cover. Annotations already indicate read-only, idempotent, non-destructive, so description complements rather than contradicts.

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 efficient and front-loaded with the core purpose in the first sentence. It then adds structured use cases and a clear explanation of the response field. Slightly verbose due to multiple use cases and detailed response semantics, but each section is purposeful and well-organized.

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 covers the output format and the meaning of key fields, which is enough for correct invocation. It is complete for the task—no ambiguity remains about what is returned or how to interpret the result. The presence of an output schema is not required, but the description substitutes it well.

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 describes the single parameter (project_id with description 'Project ID (UUID)'), so schema coverage is 100%, earning the baseline of 3. The description does not add new parameter semantics, but it reinforces the project context. No further compensation needed.

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

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

The description clearly states the tool retrieves the JSON schema of a project in FLAT format, distinguishing it from siblings like get_graph_schema or get_schema_at_version by specifying the format and use cases. The verb 'get' with a specific resource ('schema definition of a project') makes the 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 provides explicit use cases ('Review current schema before making updates', 'copy schema as template', etc.) and implicitly contrasts with version-specific tools. It names the format required for related tools (create_project, update_schema), aiding selection. It does not explicitly exclude alternatives, but the use cases are specific enough.

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 the tool read-only, idempotent, and non-destructive; the description adds content-level transparency by enumerating the exact topics covered, including nuanced rules like the __policy__ adoption conditions and fail-closed behavior on null links. No contradiction exists.

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 dense single lead sentence plus a list; all items add real information about the tool's coverage. It is longer than average but no wasted words, and the purpose and usage are front-loaded.

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 no parameters and its behavior is fully covered by annotations. The description enumerates the entire scope of the reference — policy, computed columns, constraints, audit, admin_write, user FK attribution, and batch reading — so an agent can decide whether this is the right reference without additional info.

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 and 100% coverage; the description cannot meaningfully add parameter semantics. The baseline 4 applies because there are no parameters to document.

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 verb 'Get the reference' plus the resource 'advanced schema features' names exactly what is returned. It distinguishes itself from template schema tools by saying these features are ones 'the templates do not show' and enumerates the specific topics, so an agent won't confuse it with get_schema or get_template_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?

The description says explicitly to read it 'before adding authorization or derived fields to a schema' and that it is for advanced features not shown in templates. It does not name sibling tools or state when not to use it, but the context is clear enough.

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 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 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 flag destructive behavior, but the description adds substantial context: schema and code are reverted but Neo4j data is not, the graph API is redeployed with the old schema, concurrent operations are refused, and RationalBloks updates cause temporary refusals. This exceeds annotation coverage meaningfully.

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?

Though long, every sentence earns its place: the warning is front-loaded, the non-rollback exception is explicit, and concurrency/retry behavior is described precisely. No filler or repetition beyond what is operationally necessary.

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 operation with no output schema, the description covers prerequisites, side effects, exclusions, concurrency behavior, and retry guidance. An agent has enough information to invoke it correctly and recover from rejection conditions.

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 practical value by telling the agent to resolve the version parameter via get_graph_version_history and by framing version as a commit SHA, which enriches the schema's bare 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?

Description uses a specific verb and resource: 'Rollback a graph project to a previous version.' It goes beyond a restatement by clarifying exactly what is reverted (schema AND code) and what is not (Neo4j data), which distinguishes it from generic rollback_project and other graph 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?

Clear usage context is provided: use get_graph_version_history to find the commit SHA, wait with get_job_status if another operation is running, and retry during RationalBloks updates. It does not explicitly contrast with the rollback_project sibling, so it stops short of full when/when-not alternatives 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 destructiveHint=true and readOnlyHint=false, and the description aligns with and enriches this: it warns that database data is NOT rolled back, describes the concurrent-job refusal behavior (naming the running job), and the RationalBloks update refusal. All of this goes beyond the annotations and matches them — 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?

Every sentence earns its place: the core action and warning are front-loaded, followed by workflow, use case, and concurrency details. It is somewhat long, but the length is justified by the destructive nature and the multiple behavioral constraints that need disclosure.

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 burden of explaining behavior, and it does so thoroughly: what is reverted, what is not, the redeployment follow-up, and concurrency refusals. It doesn't explicitly describe the return value, but for a mutation tool that hands off to get_job_status, this is a minor gap.

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

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

Schema coverage is 100%, so all three parameters are documented in the schema. The description adds marginal value by confirming 'version' is a commit SHA and reinforcing the get_version_history lookup, but does not introduce meaning the schema lacks. 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 (rollback), resource (project), and target (previous version) in the opening sentence. The warning clarifies the exact scope — reverts schema AND code — which distinguishes this from pure code or pure data rollbacks and from its sibling rollback_graph_project (graph vs. non-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?

Explicitly names the preparatory tool (get_version_history to find the commit SHA) and the follow-up tool (get_job_status to monitor redeployment). States the use case ('when a schema change breaks deployment') and documents refusal conditions with actionable recovery ('call it again in a few minutes').

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?

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?

The annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) already indicate safety profile. The description adds meaningful behavioral detail beyond annotations by specifying partial update semantics ('unspecified fields remain unchanged') and that it targets an existing node, which is not disclosed in 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?

Two sentences, each earning its place. The action is front-loaded, and the critical partial-update guidance is included without unnecessary verbosity. No repetition of schema or annotation content.

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 5 parameters (4 required), the description covers the essential invariant (partial update) and target scope ('deployed graph project'). Annotations cover the safety profile, and the schema documents parameters and default environment. Missing are explicit prerequisites like authentication or existence checks, but these are not necessary 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?

Schema description coverage is 100%, giving baseline 3. The description adds semantic value by clarifying the partial update behavior of the 'data' parameter ('Only send the fields you want to change'), which goes beyond the schema's generic 'Properties to update (partial update)' and helps the agent construct a correct request.

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 ('Update properties') and identifies the resource ('existing node in a deployed graph project'). It clearly distinguishes this tool from sibling tools like create_graph_node, delete_graph_node, or get_graph_node, making its purpose immediately obvious.

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 for when to use the tool: updating an existing node in a deployed graph project, with the key guideline to only send fields one wishes to change. It implies this is the update counterpart to creation/deletion but does not explicitly name alternatives or state when not to use 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 indicate readOnlyHint=false and destructiveHint=false. The description adds valuable context beyond annotations: it only persists to the database, does not deploy, and dry_run=true previews a migration without saving or deploying. This clarifies side effects and the safe preview path.

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 structured with a clear opening statement, a concise warning section, bullet-point rules, a numbered workflow, and a final note. Every section gives actionable information, and the most important caveat ('does NOT deploy') is front-loaded.

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 fully equips an agent to call the tool correctly: it explains prerequisites, schema structure rules, dry-run behavior, the save-only side effect, the mandatory next step, and how to monitor results. There is no output schema, so the reference to get_job_status fills that 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?

Although the input schema already describes all three parameters (100% coverage), the description substantially enriches the nested 'schema' parameter by specifying required keys, field defaults, allowed field types, naming conventions, and relationship requirements. This goes well beyond the schema's generic 'New graph schema' description.

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 ('Update a graph project's schema') and immediately clarifies the critical distinction: 'saves to database, does NOT deploy.' It also names the related sibling deploy_graph_staging, so an agent can distinguish this from deploy and other update 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 an explicit WORKFLOW with numbered steps: first call get_graph_schema, then modify, then call this tool, then deploy_graph_staging, then monitor with get_job_status. It includes concrete when-to-use guidance and the exclusion: this tool only saves, so you MUST call deploy_graph_staging afterwards.

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 discloses the persistence side effect ('saves to database'), the non-deployment behavior, dry_run behavior (preview without saving/deploying), and the migration risk of adding required fields without defaults. It also states that deploy_staging must be called afterward to apply changes. This goes well beyond what the annotations provide, and no contradiction exists.

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 and well-structured into CRITICAL, MIGRATION RULES, WORKFLOW, DRY RUN, and NOTE blocks. It is somewhat long and repeats the 'does not deploy / must call deploy_staging' message several times, but that repetition is justified given the risk of misuse. No section is extraneous.

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 complex tool with nested object parameters and no output schema, the description covers the full operating context: how to inspect current state, how to preview changes safely, what constraints apply, what side effects occur, and what to do after saving. 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?

The input schema already describes all three parameters at 100% coverage, and the description adds substantial meaning on top: FLAT format, no 'fields' nesting, type-specific defaults, prohibited fields/tables, and the required/default migration rule. The dry_run parameter's behavior is also explained in context. This is far richer than the schema alone.

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

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

The first sentence states the exact operation: update a project's schema, with the critical distinction that it saves to the database but does NOT deploy. This clearly separates it from deploy_staging and from the graph-related sibling tools. The follow-up rules about FLAT format and migration constraints reinforce that this is the project schema-update tool.

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

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

The WORKFLOW section explicitly orders the steps: get_schema first, optionally dry-run, then update_schema, then deploy_staging, then get_job_status. It names the sibling tools and tells the agent exactly when to use dry_run and when deployment is required. This is explicit when-to-use versus alternatives guidance.

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