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 are present and consistent, but the description adds significant behavioral context: it reveals asynchronous deployment ('2-5 min'), the returned job_id for monitoring, the requirement for a BYOC cluster_id with owned hosting retired, and that automatic fields are not needed. This goes well beyond the annotation flags and prepares the agent for real-world side effects.

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 headings (SCHEMA STRUCTURE, RULES, WORKFLOW) and an example. It is front-loaded with a clear purpose statement. Some redundancy exists (e.g., 'Use get_graph_template_schemas' appears in both Rule 8 and Workflow step 1), but overall each section earns its place given the tool's complexity.

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 thorough for a complex tool: covers schema format, rules, example, workflow, and deployment monitoring. It implies the return value is a job_id for get_job_status, but does not explicitly state the full response shape or error behavior. Given the absence of an output schema, a slightly more explicit return description would push it to 5.

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

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

Although schema coverage is 100%, the description substantially expands parameter understanding. It provides a full graph schema format, field types, cardinality options, hierarchical node examples, and rules that clarify the 'schema' parameter. It also explains the cluster_id requirement and why it's mandatory, adding meaning beyond the schema's brief property 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 opens with a specific verb+resource: 'Create a new Neo4j graph database project from a hierarchical JSON schema.' This clearly distinguishes it from sibling tools like create_project (relational) and graph node/relationship creation tools. The extensive schema guide reinforces the unique functionality.

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 instructs to use get_graph_template_schemas first, then call, then monitor with get_job_status. This provides clear usage context. It does not explicitly name alternatives like create_project or say when not to use this tool, but the requirements (BYOC cluster_id, graph schema) make the appropriate use case evident.

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?

Annotations only indicate non-readonly/open-world. The description adds substantial behavioral detail: mandatory BYOC deployment with cluster_id, schema format constraints, automatic field injection, array type GIN indexing, and expected deployment time (2-5 min). 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 long but well-structured with numbered rules, clear sections, and code examples. It is front-loaded with the core purpose and each rule earns its place given the schema complexity. Slightly verbose but effectively 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?

The description covers schema construction rules, available types, backend options, prerequisites, deployment workflow, and monitoring. It even mentions the returned job_id despite no output schema, so the agent has all necessary context to invoke the tool and follow up.

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?

Even though schema descriptions cover 100% of parameters, the description vastly expands semantics: it details the flat schema format with examples, required properties per field type, automatic fields to avoid, authentication patterns, and clarifies backend_type differences and the meaning of cluster_id in the BYOC context.

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 clear action phrase: 'Create a new RationalBloks project from a JSON schema.' This specifies the verb, resource, and input format, and the lengthy schema rules distinguish it from graph-specific tools like create_graph_project.

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

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

The WORKFLOW section gives explicit steps: use get_template_schemas first, optionally choose backend_type, then monitor via get_job_status. It also notes the cluster_id prerequisite from list_clusters. However, it does not directly mention alternatives like create_graph_project, leaving the contrast to the name and siblings.

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

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

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 already declare destructiveHint: true, and the description adds valuable detail about what gets destroyed: 'removes GitHub repo, K8s deployments, Neo4j database, and credentials.' This enriches the safety profile and aligns with the annotations, with 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 a single, front-loaded sentence that states the primary action and uses a parenthetical to enumerate key effects. It is concise and every word adds value.

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

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

For a simple destructive tool with one parameter, the description fully covers what the tool does and what resources are affected. There is no output schema, but the return value is not critical for a delete operation, and the description is sufficiently complete 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?

The input schema has 100% coverage for project_id with a description ('Project ID (UUID)'). The tool description does not add additional parameter context, but the schema already fully documents the parameter, 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 clearly states the tool's function: 'Delete a graph project' and specifies the exact resources removed (GitHub repo, K8s deployments, Neo4j database, and credentials). This distinguishes it from sibling tools like delete_project (likely for non-graph projects) and delete_graph_node/delete_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 provides clear context that this is for graph projects specifically, which implicitly differentiates it from delete_project. However, it does not explicitly state when to use this over alternatives or mention any exclusions, so it falls just 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 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?

The description discloses exactly what will be destroyed (GitHub repo, K8s deployments, database), adding valuable behavioral context beyond the destructiveHint annotation. It doesn't mention irreversibility or confirmation, but the annotation already signals destructive intent, so the description sufficiently supplements it.

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

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

The description is a single concise sentence with a parenthetical clarifying the scope. Every word earns its place, and the most important information 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?

Given the tool's simplicity (one parameter, no output schema) and the destructive nature, the description is sufficiently complete. It lists the key affected resources, which is critical context for a deletion tool. A minor gap is the lack of explicit 'irreversible' warning, but annotations already convey destructiveness.

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 ('Project ID (UUID)'), and the description adds no additional semantic value for parameters. With 100% schema coverage, 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 clearly states the action ('Delete a project') and specifies the exact resources affected (GitHub repo, K8s deployments, database), distinguishing it from sibling tools like delete_graph_project. This is a specific verb+resource combination with clear scope.

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 context (full project deletion) but does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or when not to use it. It lacks direct referral to sibling tools like delete_graph_project for graph-only deletions.

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-idempotent, non-destructive operation. The description adds valuable context beyond these hints by stating it 'Creates a separate production Neo4j instance with its own credentials and database' and 'Requires paid plan,' disclosing side effects and prerequisites.

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 each sentence provides necessary information without redundancy. It is concise and efficiently 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?

For a tool with one parameter and no output schema, the description covers the core behavior and prerequisites. It does not mention potential errors or the exact response format, but given the tool's simplicity and existing annotations, it is 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?

Schema description coverage is 100% for the single parameter (project_id), so the schema already documents it. The description adds no additional parameter semantics, but the baseline of 3 is appropriate given the schema's completeness.

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: 'Promote graph staging to production' and elaborates with 'Creates a separate production Neo4j instance with its own credentials and database.' This distinguishes it from sibling tools like deploy_graph_staging and the generic deploy_production/deploy_staging by specifying graph-specific staging-to-production promotion.

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 when a graph is in staging and needs to be promoted to production, providing clear context. It does not explicitly list alternatives or exclusions, but the phrase 'graph staging to production' and the requirement for a paid plan sufficiently guide the agent on when this tool is appropriate.

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 far beyond the annotations by disclosing the asynchronous behavior (returns job_id immediately), the full sequence of steps (schema validation, code generation, Docker build, etc.), and expected duration. This is valuable behavioral context that annotations alone do not 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 concise yet information-dense, using a numbered list for clarity and front-loading the primary purpose. Every sentence adds value, 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?

Despite having no output schema, the description effectively communicates what to expect (job_id, async operation) and how to follow up. It covers the full lifecycle from invocation to verification, making it complete for 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?

The schema already fully documents the only parameter (project_id) with 100% coverage. The description does not add any extra parameter-specific detail, meeting the baseline for 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 deploys a graph project to staging, listing a specific verb, resource, and environment. It distinguishes itself from siblings like deploy_graph_production and deploy_staging by explicitly mentioning 'graph project' and 'staging 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?

The description provides clear context for when to use the tool (deploying graph projects to staging) and even recommends follow-up tools (get_job_status, get_graph_project_info). However, it does not explicitly state when not to use it or mention alternatives for production deployments.

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 it is a write operation and not idempotent. The description adds the 'requires paid plan' constraint and clarifies the promotion concept. However, it does not disclose potential side effects like overwriting production or the deployment process, so it adds limited behavioral context beyond 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 sentence that immediately conveys the action and a key requirement. It is concise with no wasted words or unnecessary detail.

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 one-parameter tool with no output schema, the description provides the core action and a prerequisite. It is sufficiently complete for the tool's simplicity, though it could mention the outcome or confirmation of promotion. Still, the combination of name, description, and schema covers the essential 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?

The schema covers 100% of the single parameter with a description of 'Project ID (UUID)'. The tool description does not add any additional meaning to this parameter, so it relies on the schema, which adequately documents 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 clearly states the tool's function: 'Promote staging to production'. The verb 'promote' is specific and distinguishes it from sibling tools like deploy_staging or deploy_graph_production. The resource is production, making 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 clear context: it is used to promote staging to production. It also mentions the prerequisite of a paid plan. However, it does not explicitly mention alternatives or exclusions, though sibling tool names imply the distinction. This is clear context without exclusions.

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

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

The description goes well beyond the annotations by disclosing the full sequence of side effects (schema validation, Docker build, GitHub commit, Kubernetes deployment, migrations), the asynchronous return behavior, typical duration, and a detailed failure checklist. This is rich behavioral context that annotations do not provide, and 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 structured and information-dense: purpose, numbered steps, asynchronous behavior, duration, failure checklist, and follow-up tools. Every sentence adds value, and the format makes it easy to scan for key actions and troubleshooting steps.

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 immediate return of a job_id, how to monitor progress, expected duration, common failure reasons, and how to verify success. This gives an agent the operational context needed to use and follow up on the deployment 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?

The input schema already has 100% coverage for project_id with a clear description. The tool description does not add new parameter-level semantics beyond the schema, but it does not need to since the schema is sufficient. 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 deploys a project to the staging environment and enumerates the steps involved. It distinguishes this from production deployment tools by the staging focus, but does not explicitly differentiate it from the sibling deploy_graph_staging, leaving some ambiguity about which project type it applies to.

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

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

It gives clear usage context: the operation is asynchronous, returns a job_id, should be monitored via get_job_status, and final success can be checked with get_project_info. However, it does not mention when to prefer this over deploy_staging alternatives or exclude cases like graph projects, so it lacks explicit when-not-to-use 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 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds that the tool returns hierarchical schema with nodes and relationships, which is useful context beyond annotations, but does not disclose potential response size, versioning behavior, or other operational 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 three short sentences, front-loaded with the core action. Each sentence adds meaningful clarification about the return format and the distinction from relational schemas, 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 one-parameter read-only tool with annotations covering safety, the description adequately explains what the tool does and returns. However, it does not mention whether this returns the current schema version or how versioning is handled by sibling tools like get_graph_schema_at_version, leaving a minor contextual gap.

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

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

Schema description coverage is 100% for the single parameter (project_id), so the baseline is 3. The description adds no additional parameter semantics or format details beyond what the schema already provides.

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 ('Get the graph schema definition') and resource ('of a project'), and specifies the return content as hierarchical schema with nodes and relationships. It differentiates from relational flat-table schemas, but does not explicitly distinguish from sibling 'get_graph_data_schema' or versioning alternatives, so it stops short of full 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 implies use for graph schemas rather than relational flat-table schemas, but does not explicitly state when to use this tool over alternatives like get_schema or get_graph_schema_at_version. No clear context or exclusions are provided beyond the format distinction.

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=true, idempotentHint=true, and destructiveHint=false, so the description needn't repeat those. It adds value by detailing what the templates contain: 'proper node definitions (description, flat_labels, schema with flat field definitions), relationship configurations (from, to, cardinality, data_schema), and hierarchical entity nesting.' This gives the agent a concrete preview of the response content, going beyond the safety profile provided 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 slightly verbose, with emojis and capitalized emphasis, but it is well-structured: it starts with the core purpose, then adds the 'use first' guidance, lists template contents, enumerates available templates, and ends with a practical tip. Every sentence adds useful context, though the use of emojis and excessive emphasis could be trimmed for a cleaner agent-facing description. It is not overly long for the information conveyed.

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 has no parameters and no output schema, the description compensates by clearly explaining what the tool returns (pre-built schemas) and what they include. It also situates the tool in a workflow ('USE THIS FIRST when creating a new graph project') and provides template categories. However, it does not specify the exact data structure or return format in detail, relying on high-level descriptions like 'schema with flat field definitions' and 'data_schema'. This is sufficient for a simple read-only template getter but leaves some room for interpretation.

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 description has no parameter semantics to explain. Per guidelines, a 0-parameter tool gets a baseline of 4. The description doesn't need to add parameter details because there are none. It does mention available templates, which could hint at selection, but since there is no parameter, this does not conflict with the schema. The baseline score of 4 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 pre-built graph template schemas for common use cases.' It specifies a specific verb ('get'), a concrete resource ('pre-built graph template schemas'), and the intended use case. It also distinguishes from sibling tools like 'get_template_schemas' by emphasizing the 'graph' context and lists specific available templates (Social Network, Knowledge Graph, Product Catalog), making the 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?

The description provides explicit usage guidance: '⭐ USE THIS FIRST when creating a new graph project!' This clearly indicates when to use relative to other tools. It also instructs that templates can be used directly with 'create_graph_project' or modified, and advises studying the templates before creating custom schemas. This directly addresses when and how to use the tool versus 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 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: expected deployment duration (2-5 minutes), status semantics, and guidance on handling prolonged or failed states. It surfaces potential pitfalls (schema format) and recommended follow-ups, which is genuine additional 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?

The description is well-organized with clear labels (STATUS VALUES, TIMELINE) and each sentence carries useful information. It is slightly longer than the absolute minimum but remains readable and efficient. The front-loaded purpose sentence followed by structured details earns a strong score, though minor trimming could make it even tighter.

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 one-parameter, read-only status tool with no output schema, the description is remarkably complete. It covers status semantics, expected timing, abnormal conditions, and specific next actions. The annotations handle safety, and the description fills all practical usage gaps, making it fully self-sufficient for an agent.

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 job_id as 'Job ID returned from deployment operations' with 100% coverage. The description does not add syntactic details about the parameter, but it does provide context about deployment jobs (statuses, timelines). This meets the baseline for high schema coverage without needing extra parameter elaboration.

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: 'Check the status of a deployment job.' It also enumerates the status values (pending, running, completed, failed), making the specific resource and operation unambiguous. This distinguishes it from sibling tools like get_project_info, which provides broader project details.

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

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

Explicit guidance is provided for when to use this tool versus alternatives. The description instructs to check get_project_info when status is 'running' for >10 minutes or when 'failed', and even prescribes checking schema format in failure cases. This clearly delineates the tool's scope and escalation paths.

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?

The description goes well beyond the annotations, which only indicate readOnly and idempotent. It explains the meaning of deployment statuses (Running, Pending, CrashLoopBackOff, ImagePullBackOff) and provides actionable troubleshooting steps, enriching the agent's understanding of what to expect and how to react.

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, then provides structured, valuable troubleshooting details. It is longer than minimal but each sentence contributes meaningful information, especially the status explanations and remediation steps.

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 thoroughly covers what the tool returns (deployment status, resource usage) and explains how to interpret the statuses. It also anticipates common issues and directs the user to relevant next steps, making it highly complete for a read-only informational 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 already describes the single parameter (project_id as UUID) with 100% coverage. The description does not add parameter-specific semantics beyond what the schema provides, 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 clearly states the tool's function: 'Get detailed project info including deployment status and resource usage.' This provides a specific verb and resource with detailed scope, and the emphasis on deployment status and resource usage distinguishes it from sibling tools like get_project and get_project_usage.

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 (checking deployment status and resource usage) and explicitly recommends an alternative tool (get_schema) for a specific troubleshooting scenario. It does not explicitly state when not to use this tool, but the guidance is strong enough for a 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 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 annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable behavioral context beyond annotations, clarifying the return format and that the output can serve as a template for create_project/update_schema. This is useful supplemental information, though it does not delve into hidden behaviors like rate limits or auth.

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 well-front-loaded with the core purpose. The USE CASES section is valuable, but there is redundancy: 'in FLAT format' appears twice (first and last sentences). The last sentence repeats the format example, slightly reducing conciseness, though overall it remains compact and 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?

For a simple one-parameter read-only tool, the description is largely complete: it explains the return format, relationship to create/update operations, and practical uses. It does not mention versioning (e.g., get_schema_at_version) or template schemas, but this is acceptable given the tool's name and scope. Overall, it provides enough context for an agent to select and invoke the tool effectively.

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 sole parameter project_id is fully described in the schema as 'Project ID (UUID)', giving 100% schema coverage. The description does not add further parameter-specific detail, so the baseline of 3 applies; the schema already carries the explanatory burden.

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 'Get the JSON schema definition of a project in FLAT format' with a specific verb, resource, and output format. It distinguishes from siblings like get_graph_schema, get_schema_at_version, and get_template_schemas by emphasizing FLAT format and its relevance to create_project/update_schema.

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

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

Provides explicit use cases: 'Review current schema before making updates, copy schema as template for new projects, verify schema structure after deployment, learn the correct schema format by example.' This gives clear context but does not explicitly mention when not to use it or name alternatives, such as get_schema_at_version or get_template_schemas, so it misses the highest mark.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds the behavioral fact that the returned schema is a historical snapshot, but does not disclose return format, permissions, or other side effects. With annotations present, this is adequate but not rich.

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

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

The description is a single sentence of 10 words, front-loading the verb and purpose with no fluff. Every word earns its place.

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

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

For a simple read-only tool with two fully documented parameters and robust annotations, the description is adequate. It could benefit from a note about using get_schema for the current version, but overall it is complete for its complexity.

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

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

The input schema covers both parameters fully (100%): version as commit SHA, project_id as UUID. The description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool retrieves the schema as it existed at a specific commit, using a specific verb (get), resource (schema), and temporal scope (at a version/commit). This distinguishes it from sibling tools like get_schema (current schema) and get_version_history (history listing).

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

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

The description implies usage for retrieving historical schema snapshots, providing clear context. However, it does not explicitly mention exclusions or alternative tools for current schema, so it stops short of a 5.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description clearly states the verb 'Get' and the specific resource 'subscription status' with the details 'tier, limits, and usage'. This unambiguously distinguishes it from sibling getters like get_project or get_user_info, which target different resources.

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

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

The description provides no explicit context on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It simply states what it does, leaving the agent to infer usage from the tool name and sibling context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context by explaining the template contents (FLAT structure, type properties, relationships) and best practices, going beyond the basic read-only nature without contradicting any 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 efficiently structured with a main sentence, bullet points, and a practical tip. Every element serves a purpose: stating the function, listing template categories, and emphasizing usage. It's informative without being verbose, and the front-loaded 'USE THIS FIRST' captures immediate attention.

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 no parameters, no output schema, and a simple read-only operation, the description provides all necessary context: what templates exist, what they contain, and how to apply them. It fully prepares an agent to use the tool correctly and interpret its results.

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, so the baseline is 4. The description doesn't need to explain any parameter details, and it doesn't. It focuses on what the tool returns, which 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 retrieves pre-built template schemas for common use cases, listing specific categories (E-commerce, Team collaboration, General purpose). This distinctively differentiates it from sibling tools like get_schema or get_graph_schema, and the 'USE THIS FIRST' note establishes its unique role.

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

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

Explicit guidance is provided: 'USE THIS FIRST when creating a new project', and it suggests using templates directly with create_project or modifying them. It also recommends studying templates before creating custom schemas, offering clear when-to-use context without ambiguity.

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, 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?

The description discloses critical behavioral details beyond the annotations: it reverts schema AND code, does not roll back Neo4j data, and redeploys the graph API with the old schema. This is rich context that complements the destructiveHint annotation.

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

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

The description is three sentences long, front-loaded with the primary action, and uses a warning emoji to draw attention. Every sentence contributes useful information without verbosity.

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 rollback tool without an output schema, the description covers the essential context: what is reverted, what is not, and how to find the target version. It does not describe the return value (e.g., job ID), but this is less critical given the clear scope and the presence of related tools like get_job_status.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining how to obtain the version parameter (via get_graph_version_history), and it clarifies the effect of the environment parameter indirectly through the redeployment statement. It does not override or duplicate schema 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 clearly states the action ('Rollback a graph project to a previous version') and specifies the resource (graph project). It also distinguishes from related tools like rollback_project by noting it reverts schema and code, and by mentioning the deployment effect.

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 use get_graph_version_history to find the commit SHA, providing clear context for when this tool is appropriate. It also warns that Neo4j data is not rolled back, which implies caution. However, it does not explicitly list alternative tools for non-graph projects or 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?

The description goes well beyond the annotations by explicitly warning that 'schema AND code' are reverted and that 'Database data is NOT rolled back.' This is critical behavioral context beyond the destructiveHint=true annotation. It also outlines the redeployment monitoring step.

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. It starts with the primary purpose, includes a clear warning, then gives procedural guidance. Each sentence earns its place, and the use of emoji draws attention to the warning. It is appropriately sized for the tool's complexity.

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 fairly complete for a destructive rollback operation: it states the effect, the warning, and the follow-up steps. However, it does not describe what the tool returns (e.g., a job ID or status), which is a minor gap given there is no output 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?

With 100% schema description coverage, the baseline is 3. The description adds value by telling the user to use get_version_history to find the commit SHA, which directly informs the 'version' parameter. This contextual hint goes beyond the schema's 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 clearly states the tool's action: 'Rollback a project to a previous version.' It also specifies that it reverts schema AND code, which is a specific resource and scope. However, it does not explicitly distinguish itself from the sibling tool rollback_graph_project, so it's not fully 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?

The description provides clear context for when to use: 'Rollback is useful when a schema change breaks deployment.' It also names follow-up tools (get_version_history to find the commit SHA, get_job_status to monitor redeployment) but does not state when not to use it or mention alternatives like rollback_graph_project.

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

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

Annotations 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?

The description discloses critical behavior beyond annotations: 'This only saves the schema. You MUST call deploy_graph_staging afterwards to deploy.' It also warns about following schema rules, implying validation. This adds context on side effects and prerequisites. 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 well-structured with a clear summary line, a rule list, and a numbered workflow. The key constraint ('saves to database, does NOT deploy') is front-loaded. While lengthy, every section serves a purpose—the rules are necessary for schema correctness and the workflow for proper deployment sequence.

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 schema object, required workflow), the description covers the crucial context: what it does, what it doesn't do, how to use it in the deployment pipeline, and schema requirements. It lacks explicit return-value information, but given the absence of an output schema and the strong workflow context, the description is 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 already describes both parameters (project_id as UUID string, schema as object with nodes/relationships). The description greatly enriches the schema parameter by detailing required structure: nodes key with entities, field definitions, types, cardinality, and naming conventions (PascalCase, UPPER_SNAKE_CASE). This goes far beyond the schema description and is essential for correct invocation.

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: 'Update a graph project's schema (saves to database, does NOT deploy).' It uses a specific verb ('update') and resource ('graph project's schema'), and distinguishes from deployment tools by explicitly noting it does not deploy. This separates it from siblings like deploy_graph_staging and update_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 provides an explicit workflow: use get_graph_schema first, then update_graph_schema, then deploy_graph_staging, and monitor with get_job_status. It also says 'You MUST call deploy_graph_staging afterwards to deploy,' making the usage context unmistakable. It further references rules from create_graph_project, which serves as a guideline for schema structure.

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 idempotent and non-destructive behavior, but the description adds crucial behavioral details: saves to the database but does not deploy, and requires a follow-up deploy_staging call. It also discloses migration constraints (required fields need defaults) that affect side effects and success/failure conditions.

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 highly structured with sections (critical rules, migration rules, workflow). Every sentence provides actionable information—no filler. It front-loads the core purpose and then uses bullet-style formatting to convey dense constraints efficiently.

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 no output schema, the description covers the full operational context: prerequisites (get_schema), the update action itself, post-conditions (deploy_staging), and monitoring (get_job_status). It also includes migration-specific edge cases, making it complete for a schema-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?

The input schema already covers both parameters, but the description enriches the 'schema' parameter with deep semantics: FLAT format, no 'fields' nesting, required max_length for strings, precision/scale for decimals, 'datetime' not 'timestamp', forbidden fields and tables, and migration safety rules. This goes far beyond the schema's simple 'type' requirement.

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: 'Update a project's schema', and immediately clarifies the scope: 'saves to database, does NOT deploy.' This distinguishes it from deployment tools like deploy_staging and from read tools like get_schema, 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?

The description provides a full workflow: use get_schema first, then update_schema, then deploy_staging, and monitor with get_job_status. It also explicitly says when not to use (cannot add required field without default) and references create_project rules as prerequisites. This is exemplary when-to-use guidance.

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