inspect_sitemap_applications

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's added value is the scope limitation: results cover only direct AppModule associations, not transitive dependencies, publication state, or runtime state. That is a genuinely useful behavioral disclosure that prevents over-interpretation of results, though it says nothing about result size or pagination.

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

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

Two short sentences with zero filler, and the positive scope is front-loaded before the exclusions. Nothing is repeated from the schema or annotations.

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

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

With no output schema, the description must carry the return-value burden, and 'direct AppModule associations' is only loosely indicative of what comes back (names? IDs? counts?). It correctly bounds the tool's scope but leaves the agent guessing about the response shape and about which ID the required parameter expects.

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 only 50%: environment_profile is documented in the schema, but the required 'id' carries only a UUID pattern with no explanation of which entity's ID it is (sitemap vs. solution vs. appmodule). The description adds no parameter meaning at all, so it fails to compensate for the coverage gap on the one required argument.

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

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

The description names a specific verb (inspection) and resource (direct AppModule associations for a SiteMap), which is enough to separate it from the sibling publication/editing tools like publish_sitemap, plan_sitemap_publication, or edit_sitemap_xml. It falls short of 5 because it never states what the inspection actually returns or how it differs from adjacent solution/sitemap inspectors.

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 is only implied by the negative scope clause ('does not establish full dependencies, publication or runtime state'), which nudges the agent away from using it as a dependency or publishing check. No alternative sibling tool is named for those cases, and no prerequisites or preconditions are given, so the routing guidance is inferential rather than explicit.

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